TeX 1995 July

home *** CD-ROM | disk | FTP | other *** search

/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / dviware / ln03 / rmcs / dviln03.tex_publish (.txt) < prev next >

Wrap

LaTeX Document | 1991-10-01 | 133KB | 2,268 lines

\let\iffulldoc=\iftrue %%% Change to \iffalse if you don't have DVItoLN03 %%% working yet (any version post V3.1 will do!) \let\ifatrmcs=\iffalse %%% Leave this, unless you have RMCS's shield font! \let\ifrmcs=\iffalse %%% Leave this completely \let\ifdollars=\iffalse %%% Change to \iftrue if still using TEX$... logicals %%% Make sure that you revise this file to reflect local conditions; this %%% includes references to local versions of the \LaTeX user guide, and also %%% defining the macros \sitename and \contact % Wherever this document introduces information that may vary from site to % site, the line(s) will end with %%% SYSDEP % Such sections should be modified to match local requirements; in % particular, the definition of \contact should be changed to be the name of % the local TeX administrator, and \sitename to your favourite name for your % site \def\contact{\meta{contactname}}%%% SYSDEP \def\sitename{\meta{sitename}}%%% SYSDEP %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \iffulldoc \documentstyle[11pt,twoside,changebar,graphics]{article}\else \documentstyle[11pt,twoside]{article} \let\cbstart=\relax \let\cbend=\relax \hyphenation{post-am-ble pre-am-ble down-loa-ded sto-red} \hyphenation{re-cor-ded} \makeatletter % This redefines \@arabic to the old (V2.08) % form wherein \@arabic{ctr} (and through it, \arabic{ctr}) only % produce printed output for values of ctr > 0. % This means that \setcounter{page}{0} may be used to ensure that % such things as title pages, etc, don't bear a page number, and % also so that ``non-standard'' footnotes may be interpolated into % the text by means of \footnotetext[0]{$^\dag$ Some text}, say. \def\@arabic#1{\ifnum #1>0 \number #1% \fi} % Define this to squash up lists being used as simulated lines of DCL \def\squash{\itemsep=\z@ \relax \parsep=\z@ \parskip=\z@} \makeatother \pagestyle{headings} \textheight=21cm \newfont{\tinyss}{cmss8} \newfont{\logo}{logo10 scaled\magstephalf} \ifatrmcs \newfont{\shieldfont}{shield} \newcommand{\shield}{{\shieldfont\char`\@}} \else \let\shield=\relax \newenvironment{note}{\quote\centerline{\bf Note}}{\endquote} \newcommand{\chapend}{\clearpage \ifodd \count0\else \markboth{}{}\vspace*{\fill}% \centerline{\small This page is left intentionally blank}% \vspace*{\fill}\cleardoublepage \fi} % Uncomment the next line if you don't mind pages with nothing but numbers % \let\chapend=\cleardoublepage \newcommand{\meta}[1]{$\langle\mbox{\it #1\/}\rangle$} \newcommand{\ESC}{{\tinyss\raisebox{0.5ex}{E}\kern-.2em% \raisebox{-0.5ex}{C}}} \newcommand{\TYP}{{\tt.TYP}} \newcommand{\DVI}{{\tt.DVI}} \newcommand{\TFM}{{\tt.TFM}} \newcommand{\LN}{{\tt.LN3}} \newcommand{\DVItoLN}{{\sf DVI\-to\-LN03}} \ifdollars\newcommand{\logsep}{\$}\else\newcommand{\logsep}{\_}\fi \newcommand{\BibTeX}{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}} \newcommand{\SliTeX}{{\rm S\kern-.06em{\sc l\kern-.035emi}\kern-.06em T\kern -.1667em\lower.7ex\hbox{E}\kern-.125emX}} \newcommand{\SLiTeX}{{\rm S\kern-.06em{\sc l\kern-.035emi}\kern-.06em T\kern -.1667em\lower.7ex\hbox{E}\kern-.125emX}} \newcommand{\MF}{{\logo META}\-{\logo FONT}} \newcommand{\TeXware}{\TeX\kern-.1em ware} \newcommand{\Web}{{\sc Web}} \newcommand\DVItoVDU{{\sf DVIto\kern-.06em VDU}} \newcommand\bs{\char '134 } % A backslash character for \tt font \newcommand\verbsp{\char '40 } % The \verb* space character in \tt font \newcommand{\prompt}{{[DCL]\$}} \newcommand{\cont}{{\leavevmode\kern.06em\vbox{\hrule width.4em height .8pt}\$}} \title{DVILN03 User Guide\\for the {\sl VAXen\/} at \sitename} \author{Brian Hamilton Kelly\\School of Electrical Engineering \& Science\\ \shield\\ Royal Military College of Science\\Shrivenham} \date{30th September 1991\\For {\tt DVILN03} Version 4.1} \begin{document} \setcounter{page}{0} {\def\thefootnote{\fnsymbol{footnote}} \maketitle \begin{abstract} This document describes the operation of the {\tt DVILN03} command on the {\sl VAX\/} computer. This command activates the {\sf DVItoLN03} program, which allows a \TeX{} output file in device-independent \DVI{} form to be converted to a file which may be printed on a DEC LN03\footnote{{\sl VAX\/} and {\sl LN03\/} are registered trademarks of the Digital Equipment Corporation} laser printer. It is assumed that the reader is familiar with \LaTeX{} and has read the local \LaTeX{} User Guide~\cite{RMCS:latexguide}. Familiarity with the {\sl VAX/VMS\/} operating system is also assumed. If you have a question that you can't answer by reading this document, ask \contact. He should also be informed of any possible \DVItoLN{} bugs or undocumented anomalies. \ifrmcs\else Bugs that cannot be resolved locally at \sitename{} can be reported to the author, Brian {\sc Hamilton Kelly}, who may be contacted by E-mail as {\tt<TeX@uk.ac.cranfield.rmcs>} (on the {\sc Janet} network).\fi \end{abstract}} \newpage \pagenumbering{roman} \tableofcontents \listoffigures \section*{Acknowledgements}{\small The code for handling the Rose-style \verb+\special+s for changebar marking was added by Robin Fairbairns of LaserScan, Cambridge, UK, at version 3.1-1. The algorithms for handling the newer DEClaser printers were provided by Karsten Nyblad of TFL, the Danish Telecommunications Research Laboratories; they arrived just as all the other enhancements had been completed at version 3.9, and were integrated into this new release. My colleague Niel Kempson has provided much-needed support and encouragement, and has made many useful suggestions for enhancements over the years (his latest idea, just as I'm about to release this, is to make the program capable of handling binary files that {\em aren't\/} organized as 512-byte fixed-length records, but that will have to await a future release). Finally, I must acknowledge my great indebtedness to the dedicated band of helpers who have acted as $\beta$-site testers (and provided useful suggestions for enhancements): \begin{itemize} \item Phil Taylor (\verb+<P.Taylor@vax.rhbnc.ac.uk>+), of Royal Holloway and Bedford New College, \item Robin Fairbairns (\verb+<rf@cl.cam.ac.uk>+), \item Karsten Nyblad (\verb+<karsten@tfl.dk>+), and \item Rob Schumann (\verb+<schumann@ersvm1.dnet.nasa.gov>+), of the European Space Agency, at Frascati in Italy. \end{itemize} (and of course, the dozens of unsuspecting guinea-pigs at the Royal Military College of Science!) \newpage \section*{New and Changed Features} \markboth{SUMMARY OF CHANGES}{SUMMARY OF CHANGES} \addcontentsline{toc}{section}{New and Changed Features}\cbstart \DVItoLN{} V4.1 is a maintenance update which incorporates some minor bug fixes (mostly to handle obscure font problems). It is provided as a change file to be applied to the {\tt DVITOLN03.WEB} V4.0 file; a new version of the {\tt.WEB} file is also included, because both files have now been ``detabbed''. The following new features are added in this version:\begin{itemize} \item The \verb|/PAPER_SIZE| qualifier is introduced to allow system managers to specify the default paper size (European \verb|A4| vs.\ \verb|US|); this is necessary since the mixing of landscape and portrait orientation output on the same page requires an intimate knowledge of the size of the paper. The qualifier cannot be specified explicitly to produce output as if sent to the non-default paper size, since the switch on the back of the printer also needs to be changed, and the power cycled. \item The \verb|/VERBOSE| qualifier is introduced; in the distributed {\tt.CLD} file, this is on by default, and produces the same terminal output as earlier versions of the program. By making the default \verb|/NOVERBOSE|, or specifying this explicitly on the command line, messages to the terminal are reduced to:\begin{itemize} \item the name of the {\tt.DVI} file being processed; \item the report of the total numbers of bytes of fonts downloaded; \item the numbers of the pages processed. \end{itemize} \end{itemize} The following bugs are fixed in this version:\begin{itemize} \item Optimization of font downloading had made the program incapable of handling fonts containing more than 188 glyphs. \item All rules were output in the orientation specified in the command line, even if some of them should have appeared in the opposite orientation. \item Mixed portrait/landscape material requires knowledge of the physical paper size, because the ``origin'' in landscape mode is related to the {\em bottom\/} edge of the paper. \item Changing the orientation within a page resets the margins to the hardware defaults, which necessitates that the program change them again. \item A font that contains duplicated characters (can only happen with {\tt PK} fonts), if all characters were imaged (e.g., with {\tt testfont}), would result in an illegal font download. The program now detects such erroneous fonts, which is more than any \TeX ware or fontware does (apart from {\tt GFtoPXL})! \end{itemize} \DVItoLN{} V4.0 was \cbend the first public release since V3.1-4; other versions have been used internally at the author's site, and some of these have been circulated to a dedicated band of $\beta$-site testers---I'm very grateful for your help, gentlemen! \DVItoLN{} V4.0 introduces the following refinements and new features compared with V3.1:\begin{itemize} \item Support has been added for virtual font files; for every font, the program will attempt to open a file with name \meta{fontname}{\tt.VF}, looking in the directory referenced through the qualifier \verb|/VIRTUAL_DIRECTORY| (sites without any requirement for virtual fonts can speed processing fractionally by making the default \verb|/NOVIRTUAL_DIRECTORY|)\@. Glyphs from such a font will be imaged from the appropriate physical fonts, obeying all \meta{dvi byte} sequences in the {\tt.VF} file. \item Support for \TeX's \verb|\special| command has been expanded and improved; it is only necessary to provide sufficient characters of a keyword to identify it uniquely: since all keywords (at present) are unique in their first two letters, then only that many need be provided, although any \verb|\special| sequences will ordinarily be defined within a macro package or style option; authors of these are encouraged to write all keyword parameters in full. \item Support for two new \verb|\special| commands: \begin{description} \item[\tt landscape] Any text, rules, or graphics insertion, up to the end of the current page, or the next \verb|\special{portrait}| command, whichever occurs first, will be output in landscape orientation, regardless of whether the document is being processed in landscape or portrait mode. \item[\tt portrait] The opposite of the previous command \end{description} Note that these keywords may be used with or without the `\verb|ln03:|' prefix, since the concept of printing orientation transcends any concept of device dependence. \item The qualifiers \verb|/LEFT_MARGIN| and \verb|/TOP_MARGIN| now require that their associated values be specified using the syntax of a \TeX{} \meta{dimension}, that is, by a number (real or integer) followed by a two-letter code for a \TeX{} \meta{physical unit}; the standard units of \TeX{} ({\tt pt sp pc in cm mm dd cc}) are supplemented by {\tt mi} (for micron, i.e.~1$\mu$m) and {\tt px} (for pixel). \item The program no longer assumes that \TFM{} files will be found in the directory indicated by the logical name \verb|TEX$FONTS|; instead, this information is conveyed to the program through the command-definition file, using the \verb|/TFM_DIRECTORY| qualifier. System managers are now free to use logical names of the form \verb|TEX_INPUTS| instead, and thus conform to {\sl Digital's\/} recommendations regarding customer-assigned logical names. \item Previous versions of the program would abort upon discovering a reference to a font for which character bitmaps could not be found (in either packed or unpacked pixel files). This was somewhat user-hostile, and at variance with the proposed Level~0 DVI-Driver Standard~\cite{Hosek}, so the program now substitutes solid rules of appropriate dimensions for glyphs from such a font. A warning message will be displayed. \item A mechanism has been provided by which spurious `{\tt Page wider than TeX reported}' messages may be suppressed by the user: see the descripton of the \verb+/HFUZZ+ qualifier. For completeness of orthogonality, the complementary \verb+/VFUZZ+ qualifier is also provided, but it's extremely unlikely that this would ever be required. \item Command-line qualifiers have been provided to support {\sl Digital's\/} new DEClaser~$2100^{\dag}$\footnotetext[0]{$^{\dag}$ DEClaser and LN05/LN06 are registered trademarks of {\sl Digital}} and~2200 printers (otherwise known as the LN05 and LN06). The user can control whether printing will be in simplex or duplex mode (printing on both sides of the paper), and from which tray(s) the paper will be fed. \item Last, but definitely not least, considerable speed improvements have been made by reorganizing some data structures to reduce the likelihood of the VAX having to page fault. \end{itemize} \subsection*{V3.1 Changes} \DVItoLN{} V3.1 introduced the following refinements and new features compared with V3.0:\begin{itemize} \item Support for \TeX's \verb|\special| command was expanded and improved. Sixel (or other LN03) files may now be included using the following syntaxes within the parameter of the \verb|\special| command: \begin{itemize} \item \verb*|\special{SX |\meta{filename}\verb|}| \item \verb*|\special{ln03:plotfile |\meta{filename}\verb|}| \item \verb*|\special{ln03:sixel |\meta{filename}\verb|}| \end{itemize} These commands will not normally be inserted directly by users, but through the use of a document style option, such as \verb|graphics|, see~\S\ref{subsec:graphics}. \item The Flavio Rose \verb|\special|s are supported to draw vertical bars beside changed material. The parameters recognized are as follows, with [\,] bracketing material that may be omitted: \begin{itemize} \item \verb*|\special{ln03:defpoint |\meta{point\_no}% \verb|(|[\meta{dimen}]\verb|,|[\meta{dimen}]\verb|)}|.\\ Define a point, in terms of $x$ and $y$ coordinates on the page. Either coordinate may be omitted, when the definition takes place with the appropriate current position. This therefore defines point $p_i$ to be at $(x_i,y_i)$. \item \verb*|\special{ln03:connect |\meta{point\_pair}\verb*| |% \meta{point\_pair}[\verb*| |\meta{dimen}]\verb|}|,\\ where $$\mbox{\meta{point\_pair}}\equiv \mbox{\meta{point\_no}[\verb|/|\meta{point\_no}]}$$ Connect pairs of points together, with a rule of width (height) \meta{dimen}. If omitted, the latter reverts to the usual 2 pixels (0.4pt). The points must be capable of being connected by a rule that is either strictly vertical or strictly horizontal. The variant of \meta{point\_pair} with the intervening `{\tt/}' is used with {\tt twoside} printing to specify {\em two\/} pairs of points, one to be used on left-hand pages, and one on right-hand. \item \verb*|\special{ln03:resetpoints |\meta{first}% \verb*| |\meta{last}\verb|}| Cancel all knowledge of the coordinates of points $p_f\ldots p_l$. \end{itemize} Again, the user need not worry about creating such \verb|\special| commands directly: the style option \verb|changebar| provides the appropriate macros which are invoked by means of the commands \verb|\cbstart| and \verb|\cbend|, or by the \LaTeX{} environment {\tt changebar}. \item Program now supports an optional file specification on the \verb|/LOG| qualifier. \item Program now provides the \verb|/OUTPUT| qualifier which may be used to direct output to a different file specification (for example, onto a scratch disk), or even directly to the LN03 printer, possibly as a spooled device. \item The program now ensures that all output files are created in the user's current directory (unless overridden by {\tt/OUTPUT}): formerly, the use of a logical name could cause such files to be created in a different directory. \item Correctly reports the relative magnification of fonts loaded at non-standard sizes. \end{itemize} \subsection*{V3.0 Changes} The following enhancements were made to \DVItoLN{} at V3.0: \begin{itemize} \item Both packed and unpacked font files may now each be held in ``rooted'' or ``flat'' directory structures. \item Program can handle fonts with the \TeX{} maximum of 256 characters, which permits access to Silvio Levy's Greek fonts \item The \verb|/LOG| and \verb|/NOLOG| qualifiers permit user selection of whether the program's log file (\verb|.TYP|) is retained after processing. \item Program correctly computes the imaging area of standard European A4 paper. \end{itemize} \newpage \setcounter{page}{1}\setcounter{footnote}{0} \pagenumbering{arabic} \section{Introduction} \subsection{What \LaTeX{} does with your Source File} When any program\footnote{This document refers mostly to \LaTeX, since that is the program most commonly used at the author's site; however, it may be assumed that this includes \TeX{} and \SliTeX{} as well} of the \TeX{} family is run (\TeX, \LaTeX{} or \SliTeX), it produces two output files. One of these is the {\sl log file}, which records all the output that \LaTeX{} sent to the terminal (and a lot more besides!). On a {\sl VAX\/} implementation of \LaTeX, this file has the file type `{\tt .LIS}'\@. However, it is the other file which is of most interest because this contains all the instructions to typeset your document; this file is in a {\sl Device-Independent Format\/} which is common to {\it every\/} \LaTeX{} site in the world and has a file type of `\DVI'\@. Details of the internal format of \DVI{} files are explained within the program {\sf DVItype}, which describes the definitive method for processing \DVI{} files, but need only concern those who are writing \DVI{} processing programs. Details of most \TeXware{} files have also been published in various issues of {\sl TUGboat}, the newsletter of the \TeX\ Users' Group~\cite{TUGboat-DVI,TUGboat-TFM,TUGboat-PXL,TUGboat-PK,TUGboat-GF}. \subsection{Previewing \LaTeX{} Output} Before you can see what wonders \LaTeX{} has wrought for you, it is necessary to process this \DVI{} file. As a first stage, you should use \DVItoVDU{} to produce a representation of your document on a graphics terminal, rather than waste paper unnecessarily; the \DVItoVDU{} User's Guide~\cite{RMCS:dvitguide} and the local \LaTeX{} User's Guide~\cite{RMCS:latexguide} describe how to use this program. \subsection{Committing \LaTeX{} Output to Paper}\label{sec:font-load} However, the time will come (soon, you hope!) when you are ready to commit your document to paper; now it is necessary to process the \DVI{} file with the command {\tt DVILN03} which activates the {\sf DVItoLN03} program\footnote{The command is {\bf not \tt DVITOLN03} because, if it were, the VAX/VMS command line interpreter (CLI) would be unable to distinguish between this and the {\tt DVITOVDU} command}. For example, to process the file {\tt xxx.DVI}, resulting from \LaTeX ing {\tt xxx.TEX}, you would type: \begin{description} \item[\prompt\footnotemark] \footnotetext{In this document, the prompt from VAX/VMS is shown as {\bf\prompt}} \verb*+DVILN03 xxx+\footnote{The symbol `{\tt\verbsp}' represents mandatory whitespace (one or more spaces or tabs)} \end{description} \DVItoLN{} reads the \DVI{} file, determines which individual characters of each font are used therein and writes an output file containing the necessary instructions to download the raster patterns corresponding to each character into the LN03 printer. It then appends the necessary instructions to typeset your document using the downloaded characters. The resultant output file has the file extension {\tt .LN3}, and can be queued for printing to any LN03 laser printer queue by normal {\sl VAX/VMS\/} commands. However, because it contains many (long) escape sequences, and also takes care of all printer formatting, it must be printed with a number of special qualifiers for the print command. The full details (for those who wish to set up new laser queues) are given in Appendix~\ref{sec:queues}. The \LN{} file is full of escape sequences which are peculiar to the LN03, and will cause absolute havoc if passed to any other form of printer; therefore, take care not to queue it for printing to an ordinary line printer --- even {\tt TYPE}ing it to a VDU is {\em not\/} recommended! \subsubsection{Printing the \LN{} File}%%% SYSDEP To simplify the task of queueing the \LN{} file for printing, \sitename{} provides the {\tt TEXPRINT} command; this is actually a {\sl DCL\/} symbol\footnote{For further information regarding {\sl DCL\/} symbols, see~\cite[chapter 5]{DEC:dcl-concepts}} which may be abbreviated to its first four letters, {\tt TEXP}\@. When executed as a {\sl DCL\/} command, it invokes a command procedure which queues your file for printing on the appropriate LN03 printer. \begin{note} Most of the normal {\tt PRINT} command qualifiers ({\it eg\/ \tt /DELETE}, {\tt /COPIES=\it n}, {\it etc\/}) may be used with the {\tt TEXPRINT} command. For example, to print {\tt xxx.LN3}, deleting the file after printing three copies, and sending you a message upon completion, type: \begin{description} \item[\prompt] \verb|TEXPRINT/NOTIFY xxx/DELETE/COPIES=3| \end{description} \end{note} \section{Doing more with DVItoLN03} The {\tt DVILN03} command normally processes the whole of the \DVI{} file and translates it all to a form intelligible to the LN03. It also makes the standard \LaTeX{} assumptions, that is, that the text's {\sl reference point\/} is located exactly one inch down and one inch across from the top left-hand corner of the paper. However, qualifiers to the {\tt DVILN03} command permit explicit control over which page shall be printed first, and how many following pages are to be printed. It also allows selection of a different reference point, and even permits the paper to be ``turned on its side'', into the landscape orientation. The following sections and Appendix~\ref{sec:qualifiers} give full details of each of the qualifiers which are accepted by the {\tt DVILN03} command; these qualifiers are as follows: \begin{itemize} \item \verb|/STARTING_PAGE| \item \verb|/NUMBER_OF_PAGES| \item \verb|/TOP_MARGIN| \item \verb|/LEFT_MARGIN| \item \verb|/ORIENTATION| \item \verb|/(NO)LOG| \item \cbstart\verb|/(NO)VERBOSE|\cbend \item \verb|/OUTPUT| \item \verb|/HFUZZ| \item \verb|/VFUZZ| \item \verb|/DEVICE_TYPE| \item \verb|/PRINT_MODE| \item \verb|/(NO)DUPLEX_BY_PAGE_NUMBERS| \item \verb|/FEED_TRAY| \item \cbstart\verb|/PAPER_SIZE|\cbend \item \verb|/(NO)PK_FONT_DIRECTORY| \item \verb|/(NO)PXL_FONT_DIRECTORY| \item \verb|/TFM_DIRECTORY| \item \verb|/(NO)VIRTUAL_DIRECTORY| \end{itemize} (The last four qualifiers are {\em definitely\/} for system wizards only!) \subsection{Controlling which Pages DVItoLN03 Prints} Ordinarily, \DVItoLN{} translates all the pages in the \DVI{} file into a form which can be printed by the LN03 printer; however, if you are having difficulty in getting right a figure\footnote{Although \DVItoVDU{} is the recommended method of previewing your output, it sometimes happens that it cannot provide sufficient detail when performing this sort of proof-reading operation} on page 23 of a 200-page document, it is rather wasteful of paper to keep on printing all 200 pages (not to mention the time taken waiting for the output!) Therefore \DVItoLN{} allows the user to specify which page shall be used as the starting point for printed output; it also permits the user to control how many pages are to be processed. The value on the \verb|/STARTING_PAGE=| qualifier is used to specify the starting page number; this is given as a {\em string\/} and takes the default value `{\tt*}'. This default value will match any \LaTeX{} page number and so will normally start with the first page in your document, whatever its number. However, if you provide a single number, \DVItoLN{} will match this with the {\it first\/} occurrence of a page with that number. This means that if the pages of document \verb|MY_FILE| are numbered (0), (i), (ii), (iii), (1), (2), (3), \dots, say, then selecting \verb|/STARTING_PAGE=2| will select page (ii); there is no mechanism to select page (2) instead. (Note that {\em raw\/} \TeX{} would have had the values 0, -1, -2, -3, 1, 2 and 3 for the above page numbers, and therefore page (2) {\em could\/} be selected directly; to accommodate such numbering schemes, the \verb+/STARTING_PAGE+ qualifier accepts negative numbers.) (If you've been clever and used raw \TeX's \verb|\count1|\dots{\tt 9} to get ``fancy'' page numbers, then you can specify these extra numbers, separated by periods (`.') to the \verb|/STARTING_PAGE=| qualifier; it is for this reason that the qualifier's value must be specified as a string of characters, and not as a simple numerical value. \verb|/STARTING_PAGE=3.*.19| would select the first page where \TeX's \verb|\count0| is 3 and \verb|\count2| is 19, no matter what value was in \verb|\count1|.) The number of pages to be printed is specified as the value to the \verb|/NUMBER_OF_PAGES=| qualifier; this {\em is\/} a numerical value, and takes the default value {\tt 10000000} --- hopefully this will ensure that your whole document is printed! Therefore to ensure that the page (2) of the earlier example is printed, you would need to issue the {\tt DVILN03} command as \begin{description} \item[\prompt] \verb+DVILN03 MY_FILE /STARTING_PAGE=2 /NUMBER_OF_PAGES=4+ \end{description} thus getting pages (ii), (iii), (1) and (2). As with all {\sl DCL\/} commands and qualifiers, these may be abbreviated to the minimum to make them unambiguous; therefore the above command could also have been entered as \begin{description} \item[\prompt] \verb+DVIL MY_FILE/S=2/N=4+ \end{description} \begin{figure}[htbp] \centering \setlength{\unitlength}{0.5pt} \begin{picture}(614,795) \footnotesize \tt % Main boxes \put(0,0){\framebox(614,795){\mbox{}}} \put(0,723){\line(1,0){614}} \put(72,0){\line(0,1){795}} \put(72,723){\makebox(0,0){$\bullet$}} \put(70,729){\makebox(0,0)[br]{\tiny Ref.~Point}} \put(72,696){\line(1,0){542}} \put(72,684){\line(1,0){542}} \put(72,659){\line(1,0){542}} \put(72,131){\line(1,0){542}} \put(72,101){\line(1,0){542}} \put(135,131){\line(0,1){528}} \put(480,131){\line(0,1){528}} \put(491,131){\line(0,1){528}} \put(581,131){\line(0,1){528}} % Vectors and markers \put(0,630){\vector(1,0){72}} % left margin \put(5,630){\vector(-1,0){5}} \put(5,640){1 in} \put(72,550){\vector(1,0){63}} % \oddsidemargin \put(77,550){\vector(-1,0){5}} \put(100,560){1} \put(160,795){\vector(0,-1){72}} % top margin \put(160,790){\vector(0,1){5}} \put(165,759){1 in} \put(275,696){\vector(0,1){27}} % \topmargin \put(275,701){\vector(0,-1){5}} \put(285,705){2} \put(430,716){\vector(0,-1){20}} % \headheight \put(430,664){\vector(0,1){20}} \put(440,703){3} \put(300,659){\vector(0,1){25}} % \headsep \put(300,664){\vector(0,-1){5}} \put(310,670){4} \put(200,131){\vector(0,1){528}} % \textheight \put(200,136){\vector(0,-1){5}} \put(205,610){5} \put(135,200){\vector(1,0){345}} % \textwidth \put(140,200){\vector(-1,0){5}} \put(307,210){6} \put(460,570){\vector(1,0){20}} % \marginparsep \put(511,570){\vector(-1,0){20}} \put(496,580){7} \put(491,500){\vector(1,0){90}} % \marginparwidth \put(496,500){\vector(-1,0){5}} \put(505,510){8} \put(310,151){\vector(0,-1){20}} % \footskip \put(310,81){\vector(0,1){20}} \put(300,110){9} \end{picture} \vspace{1ex} \begin{tabular}{l@{\hspace{20pt}}l} 1 \bs oddsidemargin = 63pt & 6 \bs textwidth = 345pt \\ 2 \bs topmargin = 27pt & 7 \bs marginparsep = 11pt \\ 3 \bs headheight = 12pt & 8 \bs marginparwidth = 90pt \\ 4 \bs headsep = 25pt & 9 \bs footskip = 30pt\\ \multicolumn{2}{l}{5 \bs textheight = 43\bs baselineskip + \bs topskip (528pt)} \end{tabular}} \caption{Example \LaTeX{} Page Layout\label{fig:layout}} \end{figure} \subsection{Controlling the Appearance of the Printed Page} All \LaTeX's page layout dimensions, such as {\tt\bs oddsidemargin} are measured from a standard {\sl reference point\/}; figure~\ref{fig:layout} shows how \LaTeX{} lays out a page for the {\tt article} style using 10-point type. For special effects, you may find it useful to be able to redefine the position of this reference point when printing; the qualifiers \verb|/LEFT_MARGIN| and \verb|/TOP_MARGIN| implement this change. Some documents need so-called {\sl landscape orientation\/} for the paper, where the printed page is wider than it is high. Assuming that the page layout parameters have been suitably redefined, the \verb+/ORIENTATION=LANDSCAPE+ qualifier can be used to tell \DVItoLN{} to print the document in this orientation. (Note that single pages, or even parts of pages, can be printed in the opposite orientation, through use of suitable \verb|\special| sequences in the \TeX{} source file.) \subsubsection{Specifying a new Reference Point} The \verb|/LEFT_MARGIN=| and \verb|/TOP_MARGIN=| qualifiers (which may be abbreviated to just {\tt/LE=} and {\tt/TO=}) each require a single numeric value, followed by a two-letter abbreviation for what \TeX{} calls a \meta{physical unit}; this expresses the displacement of the reference point from the left-hand and top edges of the paper, respectively. The value may be given in any of \TeX's standard \meta{physical unit}s, with the addition of {\tt mi}, representing 1$\mu$m (micron), and {\tt px}, which represents units of {\sl pixels}\footnote{see glossary}, the basic unit of measure on the LN03; there are 300 pixels to one inch (the LN03 can therefore print at a density of 90,000 $\mbox{dots}/\mbox{in}^2$) and so, as you might expect, the default values for these qualifiers are both {\tt 300px} for \TeX's default reference point; the same effect could be achieved by specifying this value as {\tt 1in} or {\tt25.4mm} or even as {\tt72.27pt}. \subsubsection{Specifying a Different Paper Orientation} Ordinarily, \DVItoLN{} produces its output assuming {\sl portrait\/} orientation for the paper (with the paper being higher than it is wide). However, you might wish to use different parameters to \LaTeX\ (\verb|\textwidth|, {\it etc\/}), such that the paper is assumed to be in {\sl landscape\/} mode; it is then necessary to tell \DVItoLN{} that it should send re-orientation commands to the LN03. This is specified by means of the \verb|/ORIENTATION=| qualifier, (which may be abbreviated to {\tt/OR=}), and takes the ``values'' {\tt PORTRAIT} or {\tt LANDSCAPE} ({\tt P} or {\tt L}); the default is {\tt PORTRAIT}. \subsection{Including Graphics Images in your Document}\label{subsec:graphics} A local extension to \LaTeX{} at RMCS permits the \DVItoLN{} program to include graphic images within a printed document. The images will typically have been captured from a graphical display by software which ``reads back'' such an image to the host computer. The only format supported at present for such an image dump requires that it be in DEC's `sixel' format; this is documented in the programmers' manuals for the LN03 printer and the VT240/1 terminals. Such files can be generated by the {\sf ReToS} program from sources written in ReGIS; provided that the correct device type is specified (\verb+LN03+ or \verb+LN03_PLUS+, as appropriate), the {\sf ReToS} output may be imported {\it verbatim}. To prepare \LaTeX{} to include such an image, include {\tt graphics} as an option to the {\tt\bs documentstyle} command; this will define five new commands, the first four of which are as follows: \begin{description} \item[{\tt\bs smallVT240}] Includes an image dump in a space 1.6inches high and $2\frac23$ inches wide, suitable for a full-screen dump from a VT240/1 terminal measuring $480\times800$ screen pixels, at 1:1 scaling \item[{\tt\bs largeVT240}] For printing a dump at 2:1 scaling, occupying 3.2in$\times5\frac13$in \item[{\tt\bs smallVis550}] For 1:1 scaled dump from a Visual 550 terminal, with $585\times768$ screen pixels, in a space measuring 1.95in$\times$2.56in \item[{\tt\bs largeVis550}] For printing a dump at 2:1 scaling, occupying 3.9in$\times$5.12in \end{description} (The fifth command, \verb|\gino|, is described in \S~\ref{subsub:gino} below.) In each case the commands take one parameter, which must be the name of the sixel dump file (including any necessary file extension). The commands ensure that a space of the appropriate size is left within the text (you will most probably use the commands within a {\tt figure} and/or {\tt picture} environment). {\sf DVItoLN03} is passed the filename and instructed to treat the file as a sixel dump (by means of \TeX's {\tt\bs special} command) through the above macros. \begin{figure}[hbtp] \iffulldoc\centerline{\smallVis550{\ifrmcs TEX$BIB:\fi openclose.small}}\fi \caption{Visual 550 Screen Dump printed by the {\tt\bs smallVis550} Command}\label{fig:small-six} \end{figure} Figures~\ref{fig:small-six} and~\ref{fig:large-six} illustrate the utility of these commands; the dumps were taken from a Visual 550 terminal. \ifrmcs It is understood by the author that the Selenar SG640 terminals in the Computer Centre are also capable of performing screen dumps to the VAX; if anyone would care to implement a program to effect such a dump, appropriate commands can be added to the definitions in {\tt graphics.sty}\fi The sixel dump will be included {\it verbatim\/} within the resulting {\tt.LN3} file by \DVItoLN; it {\bf must} include the necessary {\tt DCS} (Device Control String) sequence to introduce the dump, and finish with the {\tt ST} (String Terminator) escape sequence. Dumps for printing with the commands must specify the scaling through the third parameter of the {\tt DCS} sequence, therefore the files will commence with `{\tt\ESC P9;0;1q}'\footnote{\ESC\ represents the `escape' character} for printing with the ``small'' commands, and `{\tt\ESC P9;0;2q}' for use with the ``large'' versions; see~\cite{DEC:LN03} for further details. \subsubsection{GINO Graphics}\label{subsub:gino} Thanks to the good offices of Sqn.~Ldr.~John {\sc Baggott}, a student on 2MESE course at RMCS, a program (\verb+GINOtoSIX+) is now available which will convert the metafile ({\tt SAVDRA}) output of GINO to a suitable sixel dump, ready for inclusion in your document with the \verb+\gino+\footnote{Also defined in the {\tt graphics} style option} command. The \verb+\gino+ command takes three parameters, thus: \begin{description} \item[] {\tt\bs gino(\meta{width},\meta{height})\char`\{\meta{filename}\char`\}} \end{description} where the \meta{width} and \meta{height} are expressed in terms of the {\sf picture} environment's current \verb+\unitlength+, and reserve an appropriately sized area of the page for the included image. The \verb+GINOtoSIX+ program is documented in appendix~\ref{appx:GINOtoSIX}. \begin{figure}[btp] \iffulldoc\centerline{\largeVis550{\ifrmcs TEX$BIB:\fi openclose.six}}\fi \caption{Visual 550 Screen Dump printed by the {\tt\bs largeVis550} Command}\label{fig:large-six} \end{figure} \section{Files Used and Generated by DVItoLN03} \subsection{The \DVI{} File}\label{sec:no-extension} This file, as already explained, is generated by \LaTeX{} and contains the commands to typeset the entire document; its device-independent format~\cite{TUGboat-DVI} means that it can be processed by different {\sf DVIto}\dots{} programs to permit driving many different output devices, from VDUs and dot-matrix printers, with lowish resolutions, through laser printers, with resolutions (usually) of 300 dots per inch, right up to photo-typesetters, some of which have resolutions of 5,333$\frac{1}{3}$ dots per inch! \subsection{The {\tt .LN3} File} This file is generated by the {\tt DVILN03} command; the file {\it name\/} is the same as that specified for the \DVI{} file. These \LN{} files tend to be large (hundreds of blocks long), and there is never any point in keeping them after printing (unless you want to print further copies immediately\footnote{Even this is to be deprecated; photocopying is faster, cheaper, and doesn't tie up the printer queue.}). It is a good idea, therefore, to delete such files as soon as possible, since they can quickly consume your disk quota; the easiest way is by specifying the {\tt /DELETE} qualifier on the end of the {\tt TEXPRINT} command line. The {\tt /OUTPUT} qualifier may be used to give this output file a different file specification; this may be used to override the default action, which is to create the file in the current directory, with file extension `\LN{}' and the same name as the actual \DVI{} file opened. Thus the qualifier could be used to divert the output to a scratch disk, such as ({\tt DISK\logsep SCRATCH:}). %%% SYSDEP This file starts off, as already mentioned in section~\ref{sec:font-load}, by downloading the {\sl glyphs}\footnote{see glossary} of the necessary characters to the LN03's font memory. The format of this part of the file conforms to DEC standard~180~\cite{DEC:FontFileFormat}. \subsection{The {\tt .TYP} File} This file is \DVItoLN's equivalent of the log file generated by \LaTeX; it contains all the output (with some differences of format) that \DVItoLN{} sent to your terminal (details of font loads, {\it etc\/}) and some further information regarding the whereabouts in the file of the start of each page. Assuming that the document prints satisfactorily, there is no point in keeping the {\tt .TYP} file, and so it should be deleted as soon as possible; however, if you believe that \DVItoLN{} is behaving anomalously, please keep this file to show \contact. The default behaviour of \DVItoLN{} is to delete this file providing no messages were issued; however, if any warning or error messages {\em were\/} produced, the file will be retained automatically. The \verb+/LOG+ qualifier may be used to ensure retention of the {\tt.TYP} file; conversely, the {\tt/NOLOG} qualifier will {\em never\/} keep the file. The {\tt/LOG} qualifier may optionally take a file specification to override part or all of the default specification for the log file; if this is used, the file will always be retained. \subsubsection{The {\tt /VERBOSE} Qualifier}\cbstart During operation, the program reports on the terminal the full specification of all files read (the input {\tt.DVI} file and any sixel files included through a \verb|\special| command). In addition, for each font specified, it reports the name of the font, the magnification, and how many bytes were downloaded to the printer for that font. Furthermore, it reports the total number of bytes downloaded for all the fonts printed. To reassure users that the program hasn't died if it's processing a very large input file, it also indicates what stage of processing it's reached whilst finding the initial starting page and determining which glyphs are imaged from each font. As each page of \TeX{} output is processed, the contents of \TeX's \verb|\count0| to \verb|\count9| registers are output between square brackets, entirely analogously to \TeX's own behaviour. Some users/sites find this too much for them; by specifying \verb|/NOVERBOSE|, either explicitly on the command line, or by removing the line reading {\tt default} for this qualifier in the command-language definition {\tt.CLD} file, the majority of this output can be suppressed: only the name of the input file, the total download and individual page number messages will be output (unless a problem is encountered). \cbend \subsection{Font Files Read by DVItoLN03} For every individual {\sl font}, no matter at what ``point size'' it is used, \DVItoLN{} needs to read the relevant {\tt .TFM} file, which contains the ``\TeX{} Font Metrics''. This file will also have been read by \LaTeX{} when it was processing your {\tt .TEX} source, and is read again to ensure that the fonts have not been revised, which might otherwise lead to erroneous output. Furthermore, every different {\it size\/} of each separate font requires a file describing the actual character ``rasters'', for each character's glyph. This installation (\sitename) %%% SYSDEP uses packed ({\tt .PK}) format font files, which save many of the 100,000 disk blocks formerly occupied by \TeX's libraries when {\sl expanded pixel rasters\/} in {\tt .PXL} files were the norm; however, \DVItoLN{} is capable of using either (or both) forms of font file. If your document referenced any {\sl virtual fonts\/}\footnote{see glossary}, then \DVItoLN{} will need to read the associated {\tt.VF} file(s)~\cite{TUGboat-VF}; the latter specifies how each character in the font is to be imaged, which might in turn require reference to other real or virtual fonts (or even the {\em same\/} font; virtual fonts may be recursive!) \subsubsection{Directory for \TeX{} Font Metrics Files} The \TeX{} Font Metrics files ({\tt .TFM})~\cite{TUGboat-TFM} are read by all members of the \TeX{} family, and also by many DVI processing programs, including \DVItoLN{} and \DVItoVDU\@. Just like these other programs, \DVItoLN{} needs to be able to read these files; the program is told where to look through the \verb|/TFM_DIRECTORY| qualifier. This will have been set up as appropriate by your \TeX{} administrator, and will most probably have the value \ifdollars \verb|TEX$FONTS|\footnote{This form goes against {\sl Digital's\/} recommendations regarding customer-assigned logical names, which should not contain dollar signs}\else \verb|TEX_FONTS|\fi. %%% SYSDEP Ordinary users should {\bf never} have any requirement to use this qualifier on command lines, but should you have some peculiar requirement where it is necessary to read non-standard {\tt .TFM} files, refer to appendix~\ref{appx:private-fonts}. \subsubsection{Directories for {\tt .PK} Files} Most fonts in use at \sitename{} %%% SYSDEP are in the packed font file format; all such files are stored here in the directory {\tt TEX\logsep ROOT:[FONTS.PK]}; the {\sl VMS\/} logical name {\tt TEX\logsep PK} %%% SYSDEP has been defined to reference this directory. All magnifications of the same font appear in this single directory; they are differentiated from each other by the file type extension, which consists of a number followed by the letters `{\tt PK}'---the number $N$ for any given magnification $m$ is given by \[N=\lfloor(1.2^m\times R)+0.5\rfloor\] where $R$ is the output device's resolution in dots per inch and $\lfloor x\rfloor$ represents the floor operation, yielding the largest integer $<x$. Since the LN03 has a resolution of 300 dots per inch, this equation becomes \[N = \lfloor (300 \times 1.2^m) + 0.5 \rfloor\] Therefore, an unmagnified Computer Modern Roman 10pt font would be found in {\tt TEX\logsep PK:CMR10.300PK}, whilst its \verb|\magstep 5| version would be in {\tt TEX\logsep PK:CMR10.746PK}. The \verb+/PK_FONT_DIRECTORY+ qualifier instructs the \DVItoLN{} program how to find these files, and has been assigned the default value {\tt TEX\logsep PK:}. %%% SYSDEP If you wish to access your own private font files, refer to Appendix~\ref{appx:private-fonts}. Alternatively, packed pixel font files may be held in a directory tree, as is done at \sitename{} %%% SYSDEP with unpacked raster files; Appendix~\ref{sec:queues} provides the details. \subsubsection{Directories for {\tt .PXL} Files} Any expanded raster pixel files are stored in a directory tree with a ``pseudo-device'' {\tt TEX\logsep PXL\_ROOT:} as its root: {\tt TEX\logsep DISK:[TEX.FONTS.PXL.]} is the definition used at \sitename{} for this logical name. Below this root are directories with numerical ``names''; the value of the name $N$ for any particular font magnification $m$ may be derived as follows:\[N = \lfloor (1.2^m \times 5 \times R) + 0.5\rfloor\] where $R$ is the output device's resolution\footnote{The factor $5$ arises from the relationship between \TeX's default {\tt\bs magnification} of {\tt1000} and the default resolution of 200 dots per inch, which was the assumed resolution of all early font files}. Since the LN03 has a resolution of 300 dots per inch, this equation simplifies to \[N = \lfloor (1500 \times 1.2^m) + 0.5 \rfloor\] hence the unmagnified fonts are in directory {\tt TEX\logsep PXL\_ROOT:[1500]}; this translates to {\tt TEX\logsep DISK:[TEX.FONTS.PXL.1500]} at \sitename. Similarly, those at \verb|\magstep 3| are in directory {\tt TEX\logsep PXL\_ROOT:[2592]}. The \verb+/PXL_FONT_DIRECTORY+ qualifier instructs the \DVItoLN{} program how to find these files; at \sitename, %%% SYSDEP this has been assigned the default value {\tt TEX\logsep PXL\_ROOT:}. Alternatively, unpacked pixel font files may be held in a single flat directory, as is done at \sitename{} %%% SYSDEP with packed pixel files; Appendix~\ref{sec:queues} provides the details. \subsubsection{Directory for Virtual Font Files} The program needs to be able to read {\tt.VF} files for any virtual fonts used in the document; in fact, for {\em every\/} font referenced, the program checks firstly whether the font is virtual by looking for such a {\tt.VF} file: only if such a file cannot be found does the program attempt to find files containg raster information instead. The program looks for these files in the location associated with the \verb+/VIRTUAL_DIRECTORY+ qualifier; it may be found convenient to keep such files in the same directory as the \TeX{} Font Metrics. At \sitename, this qualifier is given the value {\tt TEX\logsep FONTS:}, thus indeed placing them in the same directory. %%% SYSDEP \ifrmcs\else If documents at \sitename{} never make use of virtual fonts, then the default should be made \verb+/NOVIRTUAL_DIRECTORY+ to gain a slight improvement in speed of processing.\fi \chapend \section*{Glossary of Terms}\markboth{GLOSSARY OF TERMS}{GLOSSARY OF TERMS} \addcontentsline{toc}{section}{Glossary} \begin{description} \item[Aspect Ratio.] (1) The ratio of the height of a pixel to its width. Most laser printers have a 1:1 aspect ratio; (2) The ratio of the height of a character to its width. \item[Duplex Printing.] A feature of such newer laser printers as the DEClaser model~2200 (LN06), in which the printer contains a mechanism for mechanically turning over the sheet of paper after printing on one side before imaging a second page onto its reverse, thus producing a double-sided document. (See also {\sl Tumbled Printing}.) \item[Font {\rm or} Fount.] A character set of a specified type face and size. Usually includes upper- and lower-case letters, figures, punctuation marks, ligatures and accents. \item[Glyph.] The physical representation of a ``character'' on the printed page is known as that character's {\sl glyph\/}; thus the glyph for italic `A' ({\it A\/}) differs from that for the same character in bold face ({\bf A}). \item[Landscape Orientation.] Printing with the lines of type running parallel with the long edge of the paper, so that the paper when read is wider than it is high. \item[Packed Pixel Files.] In 1985, Tomas Rokicki designed this format, which is now capable of being used by the majority of \TeXware. By utilizing clever data compression techniques, disk occupancy for font files is reduced by 50--80\%. \item[Page Orientation.] With standard paper (either A4 [297mm$\times$210mm] or US [11in$\times$8$\frac12$in]), printing can run parallel to either the short or the long edges; these orientations are known as portrait or landscape, respectively. \item[Pixel.] \DVItoLN{} treats the sheet of paper on which a page will appear as a two-dimensional array of tiny dots known as pixels (short for ``picture elements''); pixels may be either black or white. The number of such pixels per inch, horizontally {\it and} vertically, is determined by the {\sl resolution\/} and {\sl aspect ratio\/} of the printing device. The total printable area of the LN03 (on A4 paper) is $2400\times3400$ pixels. \sitename{} %%% SYSDEP has a number of Digital LN03-Plus laser printers with a resolution of 300 dots per inch and an aspect ratio of 1:1. \item[Portrait Orientation.] Printing with the lines of type running parallel with the short edge of the paper, the normal form for books, with the page higher than it is wide. \item[Raster.] In the same way that a television screen is scanned as a {\sl raster\/} of horizontal scan lines, so each character's glyph is built up from rows of pixels. The representation of any character can then be said to occupy a certain number of {\sl rows\/} and {\sl columns\/}. \item[Recto Pages.] The right-hand pages in a book, like \ifodd\count0 this one\else the one opposite\fi. \item[Resolution.] The number of picture elements (``pixels'') appearing per linear or square inch (or suitable metric measure). \item[Simplex Printing.] This is the normal mode of printing with laser printers, except for those that can support {\sl Duplex Printing\/}; text and graphics are imaged on one side of the paper only. {\bf N.B.} Before attempting to pass such sheets through the printer a second time to print on the reverse of each sheet (``poor man's duplex''), check the manufacturer's documentation to ensure that this will not cause damage to your printer. \item[Tumbled Printing.] When printing in {\sl Duplex\/} mode (see above), the reverse of each sheet will usually have its text oriented the same way round as the front side, if the paper is turned over in the manner of reading a book. This (when combined with {\sl Portrait\/} orientation) means that the pages can be bound along the long edge of the paper to form a book. Sometimes it is desirable to bind the document along the short edge (like a flip-chart), or more often, along the long edge for {\sl Landscape\/} oriented books; in this case, {\sl Tumble Mode Printing\/} would be selected so that the {\it verso\/} pages are printed `upside-down'---the double-page spread would then have both pages, when bound, in the same apparent orientation. \item[Unpacked Pixel Files.] The original means of representing the fonts used by \TeX{} was in the form of unpacked rasters. Each row of pixels within the character's raster is represented by the appropriate number of 32-bit words; therefore a glyph occupying 65 rows of 36 columns would require {\em two\/} words per row (wasting 28 bits in each row), and thus require a total of 130 words or 520 bytes. In addition, there are a number of other parameters required for each character's glyph, so this character would occupy at least 540 bytes of disk space. \item[Verso Pages.] The left-hand pages in a book, like \ifodd\count0 the one opposite\else this one\fi. \item[Virtual Fonts.] One of the extensions to \TeX, introduced by Knuth~\cite{TeX3} in his major enhancement of 1990 (V3), is the concept of virtual fonts~\cite{TUGboat-VF}. Whilst \TFM{} files exist in the usual way for virtual fonts, and are used by \TeX{} in exactly the same manner as those for ``real'' fonts, there are no associated pixel files. Instead, a {\tt.VF} file provides a mapping for each character in the virtual font; the mapping for any single character might reference one (or more) characters from some real font(s), or perhaps construct a glyph from some pattern of horizontal and vertical rules---{\tt.VF} files contain sequences of \meta{dvi command}s for each glyph, which are interpreted by the output driver. Thus virtual fonts can contain, for example, accented letters formed from a combination of two or more characters, but treated by \TeX{} as single `letters', and hence capable of being considered by \TeX's hyphenation routines. Furthermore, since each character can be `tuned' individually, better positioning of accents on such things as upper-case letters can be achieved. \end{description} \chapend \appendix \section[Information for System Managers]{How to configure the Directories and set up a Printer Queue for an LN03}\label{sec:queues} This appendix provides details for system managers configuring an LN03 into their system to support \TeXware. \subsection{Creating the Appropriate Directories} \DVItoLN{} will work with packed or unpacked pixel files, or a mixture of both. It does not support the use of generic font files, and is unlikely to, since that would require it to read the entire raster into memory to determine the bounding box size, whilst the other formats both include this information in the file, so the glyph's raster can be copied piecemeal. In common with other binary files used by \TeXware{} under VMS, such files {\em must\/} be organized as 512-byte fixed-length records: if you've got them in some other mode, such as Stream-LF or variable-length no-carriage-control, then either recreate them with a VMS implementation of {\sf GFtoPK, GFtoPX}, or fetch them from somewhere else that {\em does\/} have them in the right format. \subsubsection{Where to put Packed Pixel ({\tt.PK}) Files} At RMCS the {\tt.PK} files of all the fonts supported are placed in {\bf one} directory; this is referenced {\it via\/} the logical name {\tt TEX\logsep PK}, and the latter provided as the default value for the \verb+/PK_FONT_DIRECTORY+ qualifier\footnote{Not forgetting to include a `{\tt:}' at the end of the logical name; the qualifier provided {\em must\/} legally be capable of being prefixed to a partial file specification, which may contain a directory part} in the \verb+DVITOLN03.CLD+ command definition file. Each font file should include the magnification and resolution indication in its file type extension. On the system at RMCS, {\tt TEX\logsep PK} points to {\tt TEX\logsep ROOT:[FONTS.PK]}, and looks like this: {\small\tt\obeylines\obeyspaces Directory TEX\logsep ROOT:[FONTS.PK] $\vdots$ CMBX10.300PK;1 CMBX10.329PK;1 CMBX10.360PK;1 CMBX10.432PK;1 CMBX10.518PK;1 CMBX10.622PK;1 CMBX10.746PK;1 CMBX10.896PK;1 \dots $\vdots$ CMINCH.300PK;1 \dots $\vdots$ CMR10.300PK;1 CMR10.329PK;2 CMR10.360PK;2 CMR10.432PK;1 CMR10.518PK;1 CMR10.622PK;1 CMR10.746PK;1 CMR10.896PK;1 CMR17.300PK;2 $\vdots$ \noindent Other sites may prefer to put the font files for different magnifications into separate directories, in the fashion used at RMCS for {\em unpacked\/} pixel files (see below). In this case, the value provided for the \verb+/PK_FONT_DIRECTORY+ qualifier, or by the equivalence string of whatever logical it references, would end with `{\tt.]}'. \subsubsection{Where to put Expanded Raster ({\tt.PXL}) Pixel Files} At RMCS all the unexpanded raster pixel files relating to each different magnification are gathered together into separate subdirectories, with the subdirectory ``name'' reflecting the magnification and resolution. A pseudo-device {\tt TEX\logsep PXL\_ROOT:} is then defined such that these subdirectories then appear as ``actual'' directories of the pseudo-device. On our installation, we define the latter as follows:\begin{description} \squash \item[\prompt] {\tt DEFINE/TRANSLATION\_ATTRIBUTE=CONCEALED TEX\logsep PXL\_ROOT -} \item[\cont] {\tt TEX\logsep DISK:[TEX.FONTS.PXL.]} \end{description} The \verb+/PXL_FONT_DIRECTORY+ qualifier is given this logical name as its default value. A listing of this directory might look like this: {\small\tt\obeylines\obeyspaces Directory TEX\logsep PXL\_ROOT:[000000] 1200.DIR;1 1350.DIR;1 1500.DIR;1 1643.DIR;1 1800.DIR;1 2160.DIR;1 2592.DIR;1 3000.DIR;1 3110.DIR;1 3732.DIR;1 4479.DIR;1 5375.DIR;1 6450.DIR;1 7740.DIR;1 Total of 14 files. \noindent The files in the individual directories have file type {\tt.PXL}; that for the unmagnified fonts might look (in part) like this: {\small\obeylines\obeyspaces\tt Directory TEX\logsep PXL\_ROOT:[1500] $\vdots$ AMSSMC10.PXL;1 AMSSMC40.PXL;1 BLACK.PXL;1 CIRCLE10.PXL;3 CIRCLEW10.PXL;3 CMB10.PXL;1 CMBSY10.PXL;1 CMBX10.PXL;1 CMBX12.PXL;1 CMBX5.PXL;1 CMBX6.PXL;1 CMBX7.PXL;1 CMBX8.PXL;1 CMBX9.PXL;1 \dots $\vdots$ CMR10.PXL;3 $\vdots$ \noindent The directory which contains the \verb|\magstep 3| files might look like this: {\small\obeylines\obeyspaces\tt Directory TEX\logsep PXL\_ROOT:[2592] $\vdots$ CMBX10.PXL;1 CMBX5.PXL;1 CMBX7.PXL;1 $\vdots$ CMR10.PXL;1 $\vdots$ \subsection{Modifying the Command Definition File} The distributed installation kit for \DVItoLN{} includes a file {\tt DVITOLN03.CLD} which defines the {\tt DVILN03} command and its qualifiers. Since individual sites may have different mixtures and arrangements for their packed and unpacked (if any) pixel files, and the commonest type of output device in use, the sensible place to allow for these changes is in this file. Therefore it should be modified to reflect local requirements in the definitions of the following qualifiers: \begin{itemize} \item \verb|/DEVICE_TYPE|, \item \cbstart\verb|/PAPER_SIZE|, \item \verb|/(NO)VERBOSE|,\cbend \item \verb|/TFM_DIRECTORY|, \item \verb|/PK_FONT_DIRECTORY|, \item \verb|/PXL_FONT_DIRECTORY|, and \item \verb|/VIRTUAL_DIRECTORY|. \end{itemize} Furthermore, the line reading `{\tt image "TEX\logsep EXE:DVITOLN03"}' may need to be changed to reflect the location of the program's executable image at your site. The \verb|/DEVICE_TYPE| qualifier has its possible values defined by that section of the \verb|DVITOLN03.CLD| file headed `\verb|define type PRINTERS|'\@. Just one of these values should be marked as `\verb|default|'; the distributed version makes \verb|LN03| the default printer type. \cbstart Similarly, the \verb|/PAPER_SIZE| qualifier is set by marking the default definition in the `\verb|define type PAPER_TYPES|' section as either \verb|A4| or \verb|US|.\cbend As described above, at RMCS we have our unpacked pixel files in a tree structure, whilst our packed files are all in a single directory, with logical names defined appropriately. Therefore, the relevant section of our {\tt DVITOLN03.CLD} file looks like this:\ifdollars \begin{verbatim} qualifier PK_FONT_DIRECTORY, negatable, default, value(default="TEX$PK:",type=$file) qualifier PXL_FONT_DIRECTORY, negatable, default, value(default="TEX$PXL_ROOT:",type=$file) \end{verbatim}\else \begin{verbatim} qualifier PK_FONT_DIRECTORY, negatable, default, value(default="TEX_PK:",type=$file) qualifier PXL_FONT_DIRECTORY, negatable, default, value(default="TEX_PXL_ROOT:",type=$file) \end{verbatim}\fi (Where the logical name {\tt TEX\logsep PK} is defined as {\tt TEX\logsep ROOT:[FONTS.PK]} and {\tt TEX\logsep PXL\_ROOT} as {\tt TEX\logsep DISK:[TEX.FONTS.PXL.]}\footnote{The latter cannot be written as {\tt TEX\logsep ROOT:[FONTS.PXL.]} because that would cause VAX Record Management Services (RMS) to attempt to interpret the expanded string {\tt TEX\logsep DISK:[TEX.][FONTS.PXL.][1500]\dots}!}) Modifications that you may wish to undertake are:\begin{itemize} \item Change either or both {\tt default=} strings to reflect the actual directory specification instead of using a logical name. \item If your site doesn't use one of these file classes at all, remove the line `\verb|default,|' from the relevant qualifier's definition. \end{itemize} At least one of these qualifiers {\em must\/} have a default or explicit value provided, through the {\tt.CLD} file or a command-line qualifier; the program cannot run without some source of pixel files. If both formats of pixel files are in use at a site, then the packed ones will be inspected before any attempt to open unpacked files. To make use of the {\tt DVILN03} command, each user must issue the DCL command\footnote{Some sort of logical name or other means of expressing the specification of the directory in which {\tt DVITOLN03.CLD} resides will most probably be required; at RMCS, we keep all such command definition files in the directory to which the logical name {\tt TEX\logsep EXE:} refers}%%% SYSDEP \begin{description} \item[\prompt] \verb|SET COMMAND DVITOLN03| \end{description} to read the (possibly revised) command definition file; \TeX nicians can do this for their users automatically by including the above \verb|SET COMMAND| in a command procedure that all users of \TeX{} execute. Even better (because the VMS Command Definition Utility isn't the fastest of beasts!) is for the system manager to add the {\tt DVILN03} command to \verb|SYS$SHARE:DCLTABLES.EXE| so that the command is always available on a system-wide basis; do this by issuing the command:\begin{description} \squash \item[\prompt]\verb|SET COMMAND DVITOLN03 -| \item[\cont] \verb|/TABLE=SYS$COMMON:[SYSLIB]DCLTABLES.EXE -| \item[\cont] \verb|/OUT=SYS$COMMON:[SYSLIB]DCLTABLES.EXE| \end{description} This command can only be executed if you have write access to the directory \verb+SYS$SHARE+\footnote{Note that this section now recommends placing the revised tables in {\tt SYS\$COMMON}, so that separate nodes in a cluster don't end up running different versions of the tables; this would not apply, of course, if \TeX{} and its friends were not installed cluster-wide.} \subsection{Creating a Forms Library for use with the Queue} The formatting imposed by the VAX printer symbiont is controlled by {\sl forms\/}; the {\tt PRINT} command takes a {\tt /FORM=} qualifier which may be used to specify the form to be used when printing any particular file. Each form defines the printable size of each page, and may specify that certain {\sl setup files\/} be output to the printer at the start of each job and/or page. A separate library of such setup files may be specified for each queue. A couple of such setup files will be required for use with an LN03, and at this installation they are held in the file \verb|SYS$LIBRARY:LN03CTL.TLB| which is a text library\footnote{It is a requirement of the printer symbiont that forms libraries be in directory {\tt SYS\$LIBRARY:}}. It is necessary, therefore, to create such a library; this need be done only once:\begin{description} \item[\prompt] \verb|LIBRARY/CREATE/TEXT SYS$LIBRARY:LN03CTL| \end{description} For printing {\tt .LN3} files, at least the following two setup files will be required: \begin{enumerate} \item {\tt RESET.TXT} --- should contain the escape sequence to reset the LN03 to its factory settings, thus clearing any error conditions. This may be just the two character escape sequence `\ESC\verb|c|', although proper resetting of an LN03-Plus requires `\ESC\verb+[!p+\ESC\verb|c|' to ensure that Tektronix mode is correctly cancelled. \item {\tt PORTRAIT.TXT} --- should contain escape sequences to use the LN03 in portrait orientation, using the appropriate paper size; at RMCS we use European A4 paper in extended portrait format; an appropriate sequence would be: `\ESC\verb*|[?22 J|\ESC\verb|[16m|% \ESC\verb|(B|\ESC\verb|)0|\ESC\verb|*<|\ESC\verb|+>|'. This setup sequence actually is required only for non-\TeX{} use of the printer; it defines the paper area to be used, selects a standard (DEC monospaced) font, and designates the G0\dots G3 character sets. None of this is strictly necessary for use by \TeX, since \DVItoLN{} puts appropriate escape sequences into the {\tt .LN3} file to control all these features; however, such a setup file would be useful for formatting ordinary (non-\LaTeX) text printing on the LN03. \end{enumerate} It may be convenient to define other setup files such as {\tt LANDSCAPE.TXT}, {\tt ELITE.TXT}, {\it etc\/}. \subsection{Defining Forms for use with LN03 Queue} Only one form is required specifically for printing \LN{} files; other forms may be defined for convenience when printing other files on the LN03. At RMCS, this form is called {\tt PLOT\logsep FORM}, since it is also used to ``format'' for printing files which constitute screen dumps taken from graphics terminals. It has been arbitrarily assigned as form number 83, and the example below uses this name and number. Of course, such nomenclature needs to be assigned suitably at each site by the system manager.%%% SYSDEP The following command would generate an appropriate form; the footnotes detail items to which particular attention should be paid: {\small\begin{description}\squash \item[\prompt] \verb|DEFINE/FORM-| \item[\cont] \verb|/DESCRIPTION="Portrait 66x80 without WRAP for laser printers"-| \item[\cont] \verb|/LENGTH=66-| \item[\cont] \verb|/MARGIN=(BOTTOM=0,LEFT=0,RIGHT=0,TOP=0)-|\footnote{No margins around the text; these could introduce spurious spaces, which might even be in the middle of an escape sequence} \item[\cont] \verb|/STOCK=A4-|\footnote{Ensure that print jobs will only be released to the printer when it contains the correct paper type.} \item[\cont] \verb|/NOTRUNCATE-|\footnote{{\tt /NOTRUNCATE/NOWRAP} to ensure that the long character records of the \LN{} files don't get broken up by the symbiont} \item[\cont] \verb|/NOWRAP-| \item[\cont] \verb|/WIDTH=80-|\footnote{The width is still specified as the maximum printable with the printer's in-built fonts, in order that any flag pages printed are of the correct width} \item[\cont] \verb|/SETUP=(RESET,PORTRAIT)-|\footnote{Invoke the appropriate setup files when the form is used} \item[\cont] {\tt\ \ \ PLOT\logsep FORM 83} \end{description}} \subsection{Setting the ``Terminal's'' Physical Characteristics} The first step, assuming that a LN03 or LN03-Plus printer has been connected to a particular terminal port of the {\sl VAX}, is to configure that port; at RMCS the terminal has been connected to \verb|_TXA4:|, %%% SYSDEP but this will obviously be installation-dependent. Therefore the examples refer to the terminal line through the DCL symbol \verb|LASER_TERM|, this can be equated to the real device by means of a DCL string assignment such as the following:\begin{description} %%% SYSDEP \item[\prompt] \verb|LASER_TERM = "_TXA4:"| \end{description} Therefore, we will need to issue a command somewhat like this (refer to the footnotes for the {\it raison d'\^etre\/} behind some of these settings): \begin{description}\squash \item[\prompt]\verb|SET TERMINAL-| \item[\cont] \verb|/PERMANENT-|\footnote{Note that this has to be done to the {\sl permanent\/} characteristics} \item[\cont] \verb|/DEVICE_TYPE=LN03-|\footnote{We set the terminal device type, using {\tt /DEVICE\_TYPE}\@. This should take care of things like {\tt /FORM}, {\tt /TAB}, {\it etc}, although we can't do any harm by mentioning these explicitly!} \item[\cont] \verb|/FORM-| \item[\cont] \verb|/TAB-| \item[\cont] \verb|/SPEED=19200-|\footnote{To improve the speed at which documents are printed, it is best if the printer is set up to its fastest speed, 19,200Bd} \item[\cont] \verb|/WIDTH=255-|\footnote{Typically, {\tt .LN3} files contain records up to about 180 characters long (including escape sequences); therefore we don't want the terminal driver to interrupt these, and insert spurious CR-LF pairs, so we set an artificially high {\tt /WIDTH} and also ensure that the ``terminal'' is set {\tt /NOWRAP}} \item[\cont] \verb|/NOWRAP-| \item[\cont] \verb|/PAGE=66-|\footnote{Other (non-{\tt.LN3}) files printed on the device need to use only 66 lines per page} \item[\cont] \verb|/NOBROADCAST-|\footnote{We don't want operator messages to terminals to get to the printer, so set it {\tt /NOBROADCAST}} \item[\cont] \verb|/NOMODEM-| \item[\cont] \verb|/NOHANGUP-| \item[\cont] \verb|/NOECHO-|\footnote{Any input from the printer (possible error status reports) should {\bf not} be echoed back to it, so set the terminal {\tt /NOECHO}} \item[\cont] \verb|/DMA-| \item[\cont] \verb| 'LASER_TERM'| \end{description} Most probably we would arrange for these operations to be performed whenever the {\sl VAX\/} is booted, by including the commands in [a command procedure which is invoked from within] \verb|SYS$MANAGER:SYSTARTUP_V5.COM| Now that we've set the characteristics of the terminal line connected to the LN03 we need to associate it with a print queue (for transparent spooling, {\it e.g.\/} if someone types the command \verb|COPY filename _TXA4:|); in this example, we're configuring the queue {\tt SEES\logsep LASER}, using device \verb|SYS$SYSDEVICE:| for spooling:-- \begin{description}\small \item[\prompt] {\tt SET DEVICE/SPOOLED=(SEES\logsep LASER,SYS\$SYSDEVICE) 'LASER\_TERM'} \end{description} Finally, we are ready to create and start the printer queue; we associate the appropriate ({\tt PLOT\logsep FORM}) default form with the queue, for use with transparent spooling printing, and arrange for the appropriate setup file to be used to clear the queue between each job:-- \begin{description}\small\squash \item[\prompt]\verb|INITIALIZE/QUEUE-| \item[\cont] \verb|/NOENABLE_GENERIC-| \item[\cont] \verb|/NOBATCH-| \item[\cont] {\tt /FORM=PLOT\logsep FORM-} \item[\cont] \verb|/NORETAIN-| \item[\cont] \verb|/LIBRARY=LN03CTL-| \item[\cont] \verb|/SCHEDULE=NOSIZE-| \item[\cont] \verb|/SEPARATE=(NOBURST,FLAG=ONE,NOTRAILER,RESET=(PORTRAIT))-|% \footnote{Note that the {\tt RESET} module is not specified here; if it were, the symbiont would insert a spurious blank page after each job} \item[\cont] \verb|/START-| \item[\cont] {\tt /DEFAULT=(NOFEED,NOFLAG,FORM=PLOT\logsep FORM)-} \item[\cont] \verb|/ON='LASER_TERM'-| \item[\cont] \verb|/RECORD_BLOCKING-| \item[\cont] {\tt\ \ \ SEES\logsep LASER} \end{description} \newpage \section{{\tt DVILN03} Command Qualifiers}\label{sec:qualifiers} As already described, the {\tt DVILN03} command takes \cbstart nineteen \cbend qualifiers; their functions are as follows:\begin{description} \item[\tt /STARTING\_PAGE=\meta{page\_string}] Takes a string-valued item which specifies the number of the first page to be processed. The format of this string may be defined, using BNF notation, as follows: \begin{itemize} \item[] \meta{page\_string} ::= \meta{string\_item} $|$ \meta{page\_string}{\tt.}\meta{string\_item} \item[] \meta{string\_item} ::= {\tt*} $|$ \meta{integer} \end{itemize} The default is `{\tt *}', which matches any page number, and hence will commence by processing the first page in the file. Each successive \meta{string\_item} is used to attempt matches with each succeeding one of \TeX's counters \verb|\count0| \dots \verb|\count9|; the first of these is by convention used for the page number. Successive counters may be used for special effects, for example, to start printing at the first page whose \verb+\count0+ is 3 and \verb+\count3+ is 6, one could use \verb+/STARTING_PAGE=3.*.*.6+. \item[\tt /NUMBER\_OF\_PAGES=\meta{positive\_integer}] Takes a value which indicates the total number of pages to be printed, including the \verb|STARTING_PAGE|\@. The default value (of {\tt 10000000}) is normally large enough to print the whole of a document! \item[\tt /TOP\_MARGIN=\meta{dimension}] Specifies how far down from the top edge of the paper the reference point is to be placed. The value may be given in any of \TeX's \meta{physical unit}s ({\tt pt sp pc in cm mm dd cc}), with the addition of {\tt mi} and {\tt px}, and the default value (of {\tt 300px}) places the reference point at the conventional one inch from the top edge. \item[\tt /LEFT\_MARGIN=\meta{dimension}] Specifies how far across from the left edge of the paper the reference point is to be placed. The value may again be given in any \meta{physical unit}, and the default value (of {\tt 300px}) places the reference point at the conventional one inch from the left edge. \item[\tt /ORIENTATION] Takes the values {\tt PORTRAIT} or {\tt LANDSCAPE} and specifies in which orientation the {\tt .LN3} file is to initialize the LN03. Unless you have taken measures to change \LaTeX's assumptions about the paper size (by changing such page layout parameters as \verb+\textheight+), use of \verb|/ORIENTATION=LANDSCAPE| will lead to text overflowing the page. \item[{\tt/\rm[\tt NO\rm]\tt LOG}] Ordinarily, \DVItoLN{} will delete the log file ({\tt .TYP}) provided no anomalies of any form were detected. However, if the program issued {\em any\/} error or warning messages, the file will be retained for later perusal. By specifying {\tt/LOG}, we can force the program always to retain the file, whilst {\tt/NOLOG} will always discard the file, even if errors/warnings were issued. Optionally, the {\tt/LOG} qualifier can take a value, which can be a complete or partial file specification to override the defaults which normally apply to this file. For example, \begin{description} \item[\prompt] \verb|DVIL/LOG=.DVI_LOG xx| \end{description} would create the log file as \verb+XX.DVI_LOG+, in the current directory, instead of as \verb+XX.TYP+. Even if there were no errors, the log file would be retained after \DVItoLN{} had finished its processing. \item[{\tt/\rm[\tt NO\rm]\tt VERBOSE}] \cbstart If \verb|/NOVERBOSE| is specified, messages indicating progress during the initial scans of the input file are suppressed, as are those showing the sizes of individual fonts downloaded, and any sixel files read by a \verb|\special| command.\cbend \item[\tt /OUTPUT] This qualifier, if used, must specify a partial or complete file specification to override the defaults for the \LN{} file; for example\begin{description} \item[\prompt] \verb|DVIL/OUTPUT=WORK$DIR:SILK_PURSE SOWS_EAR| \end{description} would direct the output to \verb+SILK_PURSE.LN3+ in directory \verb+WORK$DIR:+ (whatever that might be) instead of to \verb+SOWS_EAR.LN3+ in the current directory. \item[\tt /DEVICE\_TYPE=\meta{device name}] Specifies the type of printer on which the output file is intended to be printed; at \sitename, the default value for this qualifier is \verb|LN03|. %%% SYSDEP Other possible values are \verb|LN05| and \verb|LN06|; certain other combinations of the next three qualifiers may only be specified in association with suitable values for this qualifier. \item[\tt/PRINT\_MODE=(\meta{modelist})] Specifies whether the printer shall print \verb|SIMPLEX| (one side of paper only) or \verb|DUPLEX| (on both sides of the paper: with the LN03 and LN05 printers, \verb|DUPLEX| may only be specified in conjunction with the \verb|MASTER| mode.) For duplex printing, the user may in addition specify whether the reverse side of each sheet shall be printed ``right way up'' (\verb|NORMAL|) or ``upside-down'' (\verb|TUMBLED|); tumbled output can be useful for generating a document that's intended to be bound along its short edge (in portrait orientation). The \verb|MASTER| mode is only of use in conjunction with \verb|DUPLEX|; it causes blank pages to be generated when necessary, but all output appears printed on one side of the paper only---since blank pages are interspersed as necessary, the resultant output may be readily photocopied into a double-sided document. To specify more than one mode with this qualifier, enclose a list of modes, separated by commas, within parentheses; for example: \begin{itemize} \item[]\verb|/PRINT_MODE=(DUPLEX,NORMAL,MASTER)| \end{itemize} \item[{\tt /\rm[\tt NO\rm]\tt DUPLEX\_BY\_PAGE\_NUMBERS}] This qualifier is present by default, but only has any effect when \verb|DUPLEX| is specified within the \verb|PRINT_MODE| qualifier list; it causes a blank page to be ejected whenever two even-numbered pages follow each other, and also when two odd-numbered pages follow each other; thus odd-numbered pages always appear on the front of a printed sheet, and even-% numbered ones on the reverse. Printers (the people, not the machines!) refer to such pages as {\it recto\/} and {\it verso}, respectively, since the odd pages appear on the right, and the even ones on their reverse (the left). Note that page~0 is treated, exceptionally, as an odd-numbered page, so that it will appear on the right, since such pages often form the title or cover page of a document. Note that specifying \verb|/NODUPLEX_BY_PAGE_NUMBERS| causes both sides of every sheet (except, possibly, the last) to be printed; no blank pages will be interspersed. \item[\tt/FEED\_TRAY=(\meta{traylist})] With the LN06, it is possible to specify from which of its feed trays paper shall be fed; such specifications may apply to all the sheets printed, or the first sheet may be specified to be taken from a different source compared with that used for the subsequent sheets. The syntax requires either one entry, {\tt ALL=\meta{traytype}}, or either {\tt FIRST=\meta{traytype}} and/or {\tt REST=\meta{traytype}}: the \meta{traytype}s can be any one of: \begin{itemize} \item \verb|DEFAULT_TRAY|, \item \verb|TOP_TRAY|, \item \verb|BOTTOM_TRAY|, \item \verb|ENVELOPE_TRAY|, \item \verb|MANUAL_FEED| \end{itemize} \noindent{\sl Example:\/} \verb|/FEED_TRAY=(FIRST=TOP_TRAY,REST=BOTTOM_TRAY)| The values \verb|TOP_TRAY| and \verb|MANUAL_FEED| may be specified when using the LN05 (DEClaser~2100) printer; the program doesn't yet support the optional 1000-sheet capacity tray that may be fitted to the LN05 and LN06 (mainly because the author hasn't discovered how to address it!) Tray selection is not supported, of course, on the original LN03 printer. \item[\tt/HFUZZ=\meta{dimension}] Control the distance by which text must exceed the right margin (as defined by \TeX{} in the \DVI{} file) before \DVItoLN{} complains that `{\tt Page wider than TeX reported by $x$pt}'. When \TeX{} generates a \DVI{} file, it includes in that file information regarding the maximum width and depth of the pages created: when \DVItoLN{} processes the \DVI{} file, it will produce (and it always has produced) warning messages if any characters exceed these limits. Ordinarily, such excursions ``beyond the margins'' will not occur (at least, not without \TeX{} having issued an `{\tt overfull \bs.box}' warning itself), but some macro packages {\em do\/} permit \TeX{} to exceed the boundaries\footnote{For example, the output of {\sc Weave}, when formatted by the {\tt webmac} macros, permits lines of formatted {\sc Pascal} code to exceed the right-hand margin by up to 10pt.}. By using this qualifier with some suitable dimension, such messages can be suppressed; however, you should only use this if you truly are being overloaded by such messages, since the default is intended to inform you that \TeX{} didn't do a good job of the setting, and there really {\em will\/} be something sticking out into the margin. The default value ({\tt100sp}) corresponds to that formerly `hard-wired' into the program: this is an invisibly small distance, approximately equivalent to the wavelength of visible light(!) but is large enough to absorb any rounding errors that may have occurred. \item[\tt/VFUZZ=\meta{dimension}] This is analogous to the \verb+/HFUZZ+ qualifier above, but takes care of those occasions on which \TeX{} has set text below the bottom of the area that it has notified as being the maximum depth of the page; the related warning message from \DVItoLN{} is `{\tt Page deeper than TeX reported by $y$pt}'. The author has never found any circumstances under which \TeX{} does this, but the qualifier is available for anyone who does suffer from this warning! Once again, the default value for the qualifier is {\tt100sp}. \item[]{\sl The following qualifiers should never need to be used by ordinary users; the information below is mainly intended to help system managers:} \item[\tt /PK\_FONT\_DIRECTORY] This must specify a directory (or directory tree) in which the packed pixel files (if used) are to be found. Directory trees are indicated by having `{\tt.]}' as the last two characters of the ``directory'' specification. A logical name may be given for this qualifier, provided it resolves to an appropriate directory specification; do remember to include a terminating `{\tt:}', because the qualifier itself is used verbatim as a prefix to the file specification for each font file. If a multi-valued logical name is used, the equivalence strings must {\em all\/} reference single directories, or must {\em all\/} reference directory trees; only the first equivalence string is examined to determine whether a flat or tree structure is being used. The {\tt DVITOLN03.CLD} command definition file provided has the default value {\tt TEX\logsep PK:} for this qualifier. \item[\tt /PXL\_FONT\_DIRECTORY] This specifies the directory (or directory tree) in which unpacked pixel raster files may be found, if used. The same rules regarding use of logical names apply here as to the previous qualifier. The {\tt.CLD} file provided gives this a default value of {\tt TEX\logsep PXL\_ROOT:}. \item[\tt /TFM\_DIRECTORY] This specifies the directory (or directories) in which the \TeX{} Font Metrics (\TFM) are to be found by the program. The distributed version of the {\tt DVITOLN03.CLD} file has {\tt TEX\logsep FONTS:} as the default value for this qualifier. \item[\tt /VIRTUAL\_DIRECTORY] This specifies the directory (or directories) in which Virtual Font ({\tt.VF}) files are to be found by the program. The distributed version of the {\tt DVITOLN03.CLD} file has {\tt TEX\logsep FONTS:} as the default value for this qualifier, thus placing {\tt.VF} files in the same directory as the \TFM{} files. If virtual fonts are not in use, remove the line `\verb|default,|' from the definition of this qualifier. \item[\tt/PAPER\_SIZE] \cbstart This qualifier must have one of the values (defined in the \verb|PAPER_TYPES| section of the {\tt.CLD} file) specified as default. The value ({\tt A4} or {\tt US}) should reflect the setting of the paper size switch at the rear of the printer. As might be expected, the values prepare the program to use European ($210\times297$mm) or US Letter ($8\frac12\times11$in) paper, respectively.\cbend \end{description} \chapend \section{How to use your own Fonts with \TeX\ and DVItoLN03}\label{appx:private-fonts} Ordinary users should {\bf never} have any requirement to use the qualifiers that select the location of the \TFM\ or pixel raster files; exceptionally, however, if you need to use a special font that doesn't otherwise exist in the standard directories, these qualifiers can be used, in conjunction with process logical names, to permit access to the user's own font(s) as well as the standard ones. First of all, both \TeX{} itself and \DVItoLN{} will require access to the \TeX{} Font Metrics; as already described, these normally reside in a directory to which the logical name {\tt TEX\logsep FONTS} refers; one could, of course, simply redefine this logical name to point to the new fonts, but then neither \TeX{} nor \DVItoLN{} would be able to locate the {\em standard\/} fonts. So one might define what {\sl Digital\/} call a search-list (but the author prefers to call a multi-valued logical name), like this: \begin{description} \item[\prompt] {\tt DEFINE MY\_FONTS [MY\_DIR.TFM],TEX\logsep FONTS} \end{description} Then to run \LaTeX, one would have to say: \begin{description} \item[\prompt] \verb|LATEX/FONT_DIRECTORY=MY_FONTS: MY_FILE|\footnote{Note the `{\tt:}' after the logical name; whatever is provided as the value for the {\tt/FONT\_DIRECTORY} qualifier must legally be capable of being prefixed to a file specification} \end{description} This will allow \LaTeX{} to access both the standard and your own fonts; since your fonts precede the standard ones in the search list, \TFM{} files will be taken from your directory in preference to any of the same name that might already be in the standard location. To run \DVItoLN, it must have access not only to the \TFM{} files, but also to the pixel raster files (either packed or unpacked). Whichever file directory organization has been chosen for these (and packed and unpacked rasters can utilize different organizations), the pixel files for your private fonts {\em must\/} have the same organization. Therefore, if you have only packed pixel files, and the standard fonts are arranged in a flat directory, referenced by the logical {\tt TEX\logsep PK}, you might make the following definition: \begin{description} \item[\prompt] {\tt DEFINE MY\_PK\_FILES [MY\_DIR.FONTS.PK],TEX\logsep PK} \end{description} Alternatively, or additionally, if you have unpacked pixel rasters in a rooted directory structure, the following definition might suffice, assuming that the standard fonts are accessible through {\tt TEX\logsep PXL\_ROOT}: \begin{description} \item[\prompt] {\tt DEFINE MY\_PXL\_FILES [MY\_DIR.FONTS.PXL.],TEX\logsep PXL\_ROOT} \end{description} Then to run \DVItoLN, providing it with access to the \TFM{} and pixel files of both your own and the standard fonts, it would be necessary to invoke the program like this: \begin{description}\squash \item[\prompt] \verb|DVILN03 /TFM_DIRECTORY=MY_FONTS:|\footnote{Again, note that the `{\tt:}' is necessary on the user-defined logical name so that it may be prepended to a file specification} - \item[\cont] \verb|/PK_FONT_DIRECTORY=MY_PK:|\footnote{And/or {\tt /PXL\_FONT\_DIRECTORY=MY\_PXL\_FILES:}} \verb|MY_FILE| \end{description} Once such a private font has been proven locally in your directory, it would be better if you got your local \TeX nician to install the fonts along with the standard ones (unless there are licensing restrictions applicable to the use of the non-standard fonts), since it will save the usage of all those awkward command-line qualifiers! \chapend \section{The GINOtoSIX Program}\label{appx:GINOtoSIX} This program was written by Squadron Leader John {\sc Baggott}, who was an M.Sc.\ student at RMCS in 1987. It is written in {\sc Fortran} and has a full DCL command-line interface. \ifrmcs\else Any site that is interested in acquiring a copy of the program is welcome to request it by sending an e-mail message to the author of \DVItoLN{}, \verb+<TeX@uk.ac.cranfield.rmcs>+ ({\sc Janet}).\fi \subsection{Preparing to use {\tt GINOtoSIX}} Before first attempting to use the program, invoke its command definition, by executing the following command: \begin{description} \item[\prompt] \tt SET COMMAND TEX\logsep EXE:GINOTOSIX %%% SYSDEP \end{description} (Frequent users of the utility may care to put this command into their login command procedure.) \subsection{Using the {\tt GINOtoSIX} Program} Whatever graphics are required to be converted to sixel format must firstly be output by GINO into a pseudo-code file (using the {\tt SAVDRA} driver). Then invoke {\tt GINOtoSIX} as follows: \begin{description} \item[\prompt] \tt GINOTOSIX \meta{file\_name} \end{description} \subsubsection{Qualifiers applicable to {\tt GINOtoSIX}} The utility can take a number of optional qualifiers, as under: \begin{description} \item[\tt/SIZE=(\meta{option,\dots})] Specifies the area, in millimetres, of the sixel image. If this qualifier is not used, the default action is to copy the window size (or the paper size if windowing is not in effect) of the saved picture segment. Options are as follows: \begin{description} \item[\tt WIDTH:\meta{number}] Specifies the width in mm of the sixel image; defaults to the saved width. \item[\tt HEIGHT:\meta{number}] Specifies the height in mm of the sixel image; defaults to the saved height. \end{description} If only one option is specified, the parentheses may be omitted. {\bf N.B.} If this qualifier is used in conjunction with the {\tt/SCALE} qualifier, the action is firstly to scale, then window the image. If the {\tt/SCALE} qualifier is not used, the image is scaled to fit the size specified. \item[{\tt/\rm[\tt NO\rm]\tt FORMFEED}] Instructs {\tt GINOtoSIX} to append a form feed character to the end of the sixel file. This allows the output to be queued directly to the LN03 printer for previewing. A formfeed must {\bf not} be appended to sixel files that are to be imported into a \LaTeX{} document by the \verb+\gino+ command (from the {\tt graphics} style option). The default is {\tt/NOFORMFEED}. \item[\tt/SCALE=\meta{factor}] Scale the stored image by a factor; the default factor is $1{\cdot}0$. \item[\tt/SEGMENT=\meta{integer}] Specifies which picture segment in the {\tt SAVDRA} file is to be used for producing the image, the default is $0$. If this qualifier is not used, the maximum record length for the input file is used. \item[\tt/OUTPUT=\meta{file\_spec}] Controls where the output file will be written; \meta{file\_spec} may be a full or partial specification; if not specified, the file name will be that of the input file, and its extension will be {\tt.SIX}. \end{description} \subsection{Examples of the use of {\tt GINOtoSIX}} \begin{enumerate} \item \begin{description}\squash \item[\prompt] \verb+GINOTOSIX FRED+ \end{description} The program will read the file {\tt FRED.PIC}, and produce a file {\tt FRED.SIX} from segment 0. The size of the sixel image will be the same as the saved picture. \item \begin{description}\squash \item[\prompt] \verb+GINOTOSIX/SCALE=0.5-+ \item[\cont] \verb+ /OUTPUT=DISK$SCRATCH:[FRED]GRAPH.INC FRED.GNO+ \end{description} Read a {\tt SAVDRA} from file {\tt FRED.GNO}, and produce a half-sized image in the file specified. \item \begin{description}\squash \item[\prompt] \verb+GINOTOSIX/SIZE=(WIDTH:150,HEIGHT:100) FRED-+ \item[\cont] \verb+ /SEGMENT=1/FORMFEED+ \end{description} Reads segment 1 of {\tt FRED.PIC}, and scale the image uniformly to fit in a box 150mm wide and 100mm high. A formfeed will be appended to permit the image to be previewed by printing the output file, {\tt FRED.SIX}. \end{enumerate} \chapend\begingroup \catcode`\|=\active{\catcode`\_=\active \gdef|{\bgroup\catcode`\_=\active \let_=\_\def\\##1|{{\it##1\/}\egroup}\\}} \section{Error and Warning Messages} This chapter describes all the various informational, warning, error and fatal error messages that \DVItoLN{} can issue. Most messages attempt to be self-explanatory, but this section gives full details of the conditions under which the error can be issued, and may therefore help the user in discovering why \DVItoLN{} is unable to process his/her \DVI{} file. \subsection{Fatal Errors} The following errors indicate that \DVItoLN{} is unable to proceed further with processing your \DVI{} file; where possible, methods are suggested to allow you to circumvent the problem. All such error messages commence with the text `{\tt Fatal Error:}'\footnote{Simple, isn't it!} which precedes the texts listed below. If such an error occurs, \DVItoLN{} will exit immediately, and the program's exit status will set the DCL symbol \verb+$SEVERITY+ to $4$, thus indicating a \verb+SEVERE_ERROR+. \subsubsection{Capacity Exceeded Errors} When \DVItoLN{} is presented with input that results in it using up all of some particular internal data structure, it is unable to go on! All these errors commence with the text `{\tt Fatal Error: capacity exceeded:}'. One possible solution is to recompile \DVItoLN, using a larger value for the appropriate parameter noted below. If you find that this is necessary at your site, please inform the author of \DVItoLN, who may be contacted by electronic mail as \ifrmcs{\tt N::TEX}\else\verb|<TeX@uk.ac.cranfield.rmcs>| ({\sc Janet})\fi. However, sometimes it is possible to proceed by using the \verb|/STARTING_PAGE| and \verb|/NUMBER_OF_PAGES| qualifiers to process the \DVI{} file in two or more smaller portions, which {\em don't\/} exceed the program's limits. \begin{description} \item[\tt font file name too long (max length=$x$)] --- You've had it! The limit, $x$, set at $255$ by the \Web\ constant |name_length|, is already at the maximum permitted by VAX/RMS. \item[\tt stack size=$x$] --- \DVI{} files can contain |push| and |pop| commands; \TeX{} reports in the file the maximum number of |push|es that it uses, but the program has an overall limit of $x$, set to $100$ through the \Web\ constant |stack_size|; if this value is exceeded, it's most probably due to some \meta{dvi byte} sequence running amok in a virtual font, since \TeX{} would be very hard-pressed to issue that many |push|es. \item[\tt too many blank verso pages] --- When printing in duplex mode, with the printer ``printing'' a blank side whenever two successive odd or even pages occur, the \DVItoLN{} program has to identify all such transitions before printing commences. The current maximum is set by the \Web\ macro |max_blank_pages|, which has a value of $100$. One solution which doesn't necessitate recompiling the program is to reorganize your document so that there are fewer chapters which require an odd number of pages! \item[\tt too many glyphs $n$ > $x$] --- The total characters, $n$, in all the fonts referenced within your document exceeds the storage available, $x$. The latter quantity is set by the constant |max_glyphs| in the \Web, and currently has the value $10000$. It is unlikely that such a document could be printed, unless only a small percentage of those glyphs were actually {\em used\/} in the document, because the downloaded fonts would most probably exceed the memory available on the printer. \item[\tt too many fonts (max fonts=$x$)] --- Your document loads more than $x$ different fonts. $x$ is set by the \Web{} constant |max_fonts|, and currently is set to $100$. \item[\tt too many LN03 fonts] --- You've had it! The LN03-plus is physically unable to image glyphs from more than |max_lnfonts|$+1 (= 14)$, so the ``solution'' is to process your document in sections, such that no section invokes so many glyphs that this limit is exceeded. However, even the \TeX book and \MF book don't require this many fonts, so you've got a very convoluted document: should you perhaps speak to a typographic designer? \item[\tt too many names (name size=$x$)] --- The names of all the fonts used in your document exceed $x$ characters in total; $x$ is set by the \Web\ constant |max_names|, and is currently set to $1000$. \item[\tt too many virtual characters] --- Characters taken from a virtual font that require more than simple imaging of a single character from some real font result in the whole of the character's sequence of \meta{dvi byte}s being stored in memory. If your document makes very intensive use of virtual fonts, it may be necessary to increase |vf_size| from its present value of $10000$ \end{description} \subsubsection{Bad \DVI{} File Errors} If \DVItoLN{} encounters a malformed \DVI\ file that prevents it from making any sort of valiant attempt at processing it, the program aborts with an error message that starts `{\tt Fatal error: Bad DVI file}'; the remainder of these messages are listed below. This is indicative of a serious error in the \DVI{} file; if you didn't generate it yourself, using \TeX, perhaps it was corrupted in the process of reaching your machine. Whilst \DVItoLN{} will attempt to explain what's wrong with the file, the tool to be used at this point is {\sf DVItype}: type the command \begin{description} \item[\prompt] \verb|DVITYPE| \end{description} and follow the prompts to generate a printable analysis of the offending file. \pagebreak[3] \begin{description} \item[\tt all 223s] --- A \DVI{} file is supposed to finish with at least 4 characters having the value $223$; your file appeared to consist of nothing but this character! \item[\tt byte $m$ is not bop] --- \DVItoLN{} expected to find a |bop| command at this point in the \DVI{} file, since it was all ready to start processing a new page. $m$ indicates the byte number within the file. \item[\tt byte $m$ is not post] --- \DVItoLN{} expected to find the start of the postamble at the indicated location in the file. \item[\tt denominator is $d$] --- \TeX{} reports in the \DVI{} file the actual size of the `DVI units' used therein; in fact, they are always {\tt1sp} in \TeX{} output, although it would be feasible for other programs that generate \DVI{} files to select a different unit. \TeX{} reports the actual unit by means of a pair of integers, which, treated as a rational number, will convert `DVI units' to decimicrons ($0{\cdot}1\mu\hbox{m}=10^{-7}\hbox{m}$). Thus the value given to the denominator by \TeX{} is usually $7227\cdot2^{16} = 473628672$, because there are $2^{16}$ scaled points in a point, and there are $7227$ points in 100 inches. The numerator is then $25400000 \equiv 254\hbox{\tt cm} = 100\hbox{\tt in}$. This error message will be issued if the denominator is negative. \item[\tt first byte isn't start of preamble] --- The \DVI{} file is expected to start with the |pre| command, indicating the start of the preamble. \item[\tt ID byte is $k$] --- The second byte of the \DVI{} file indicates which version of DVI is in use; this program supports only version $2$. \item[\tt magnification is $m$] --- The \DVI{} file reports whatever \verb+\magnification+ may have been specified to \TeX; the given value is negative! \item[\tt no 223s] --- As mentioned above (see `{\tt all 223s}'), the postamble is followed by a sequence of at least four bytes having the value $223$; but this \DVI{} file didn't! \item[\tt numerator is $n$] --- See `{\tt denominator is $d$}' above. \item[\tt only $n$ bytes long] --- The \DVI{} file wasn't long enough to have contained a valid preamble and postamble, let alone any useful information! \item[\tt page ended unexpectedly] --- A page being processed finished without an explicit |eop| command, and is corrupt. \item[\tt page link $p$ after byte $q$] --- The start of a page was indicated as being so close after the start of the previous one that there were insufficient bytes to contain the necessary bytes that are required to follow the |bop| code. \item[\tt post pointer $q$ at byte $m$] --- Just after the postamble the address of the postamble itself is supposed to be stored: in the given \DVI{} file, this pointed {\em outside\/} the file! \item[\tt signature in byte $n$ should be 223] --- The {\em whole file\/} (after the end of the postamble) is supposed to be filled with the $223$ bytes mentioned above; this file started off correctly, but then degenerated into something else! \item[\tt the file ended prematurely] --- Whilst processing a page, \DVItoLN{} detected the end of the \DVI{} file. \end{description} \subsubsection{Internal Errors} These are those errors that fall into the category of ``this can't happen''. The error message commences with `{\tt Fatal Error: Internal error}'. Such errors reveal some sort of coding error: if you ever see one of these errors, please contact the author, Brian {\sc Hamilton Kelly}, providing as much information as is necessary for him to reproduce the fault; this should include either the \TeX\ source, together with any non-standard style files, or the actual \DVI{} file being processed --- the latter can be encoded with {\sf VVencode}~\cite{RMCS:VVcode} for transmission by e-mail. Reports should be sent to \ifrmcs{\tt N::TEX}\else {\tt<TeX@uk.ac.cranfield.rmcs> \sc(Janet)}\fi. \begin{description} \item[\tt (no dvi\_length)] --- Program couldn't determine the actual length of the \DVI{} file. \item[\tt (word at odd byte $n$)] --- Words written into the downloaded font `file' must start at an even byte in the file. \item[\tt (longword at odd byte $n$)] --- Longwords written into the downloaded font `file' must start at an even byte in the file. \item[\tt (empty font)] --- An internal procedure has been asked to load an unused font to the printer. \item[\tt (-ve delta x)] --- A forward displacement in an output line has somehow managed to become a backwards one, despite sorting the list into non-overlapping segments! \item[\tt (String pool overflow)] --- More \verb+\special+ strings are defined at program initialization than the program has room for. \end{description} \subsubsection{Other Fatal Errors} Certain other conditions can cause \DVItoLN{} to abandon hope; these just commence with `{\tt Fatal Error:}' \begin{description} {\sloppy\item[{\tt Bad /PK\_FONT\_DIRECTORY qualifier; doesn't end with a `]'}] --- The \linebreak[4] value provided for the \verb+/PK_FONT_DIRECTORY+ qualifier, after applying logical name translation, must end with a `{\tt]}' character; check what value is being used with this qualifier.} \item[{\tt Bad /PXL\_FONT\_DIRECTORY qualifier; doesn't end with a `]'}] \hfil --- \linebreak[4] The value provided for the \verb+/PXL_FONT_DIRECTORY+ qualifier, after applying logical name translation, must end with a `{\tt]}' character; check what value is being used with this qualifier. {\sloppy\item[\tt Bad /\meta{qualifier} value] --- The value provided with the indicated qualifier does not form a valid integer.} {\sloppy\item[\tt Bad pk file---more bits than required] --- The packed pixel file currently being read (as shown by the preceding `{\tt Font \meta{fontname}}') provides more bits for a character packet than indicated in the character's preamble.} Replace the offending font; use {\sf PKtype} to analyze the pixel file. \item[\tt Bad pk file! Bad packet length] --- The packed pixel file contains a character packet of an illegal length. Replace the offending font. \item[\tt Bad pk file, pre command missing] --- The packed pixel file doesn't \linebreak[4] commence with the requisite |pre| command. Replace the offending font. \item[\tt Bad pk file; unexpected byte: $p$] --- Whilst reading a packed pixel file, the byte value $p$ was met: this was invalid in the current context. Replace the offending font. \item[\tt Bad pk file, wrong version] --- The packed pixel file is of a software version incompatible with the \DVItoLN{} program. Replace the offending font. \item[\tt Couldn't create \meta{filename}] --- \DVItoLN{} was unable to create the file indicated: check that you have write access to the current default directory, or that designated by the \verb+/OUTPUT+ qualifier. {\sloppy\item[\tt Couldn't open \meta{filename}. Status=\meta{VMS\_Error}] --- When \DVItoLN{} attempted to open the indicated file (for reading), it failed: the VMS-style error was reported by the run-time system. Perhaps the file's organization is incompatible with the type expected by the program, which generally expects text files to be variable-length, with carriage-return carriage control, and binary files to consist of 512-byte fixed-length blocks.} {\sloppy\item[\tt Font not loaded, TFM file \meta{filename} can't be opened] ---\DVItoLN{} \linebreak[4] was unable to locate the indicated \TFM{} file: it must be on your system somewhere, otherwise \TeX{} would have failed too!} \item[\tt no more virtual font bytes] --- Whilst processing a glyph taken from a virtual font, the program used up all the stored characters: really this should be classed as an internal error, and reported to the author. \item[\tt Font not loaded, bad scale ($s$)] --- The \TFM{} file indicated that the font was scaled to an impossibly high value, or negatively. Use {\sf TFtoPL} to analyze the \TFM{} file. \item[\tt Font not loaded, bad design size ($d$)] --- The \TFM{} file indicated that the font's design size was negative or an impossibly large value. Use {\sf TFtoPL} to analyze the \TFM{} file. \item[\tt No device type specified] --- No default value was provided for the qualifier \verb+/DEVICE_TYPE+. Specify an explicit value, and get your \TeX nician to modify the {\tt DVITOLN03.CLD} file to reflect the local environment. \item[\tt No file name provided] --- You'd have been extremely sneaky to get this error; you've managed to bypass DCL's check that a filename be specified to be processed by the program! Be more sensible! {\sloppy\item[\tt ---not loaded, bad TFM file] --- The \TFM{} file didn't specify a valid \linebreak[4] range of characters as being resident in the font. Use {\sf TFtoPL} to analyze the \TFM{} file.} \item[\tt PXL file has bad format] --- The unpacked pixel raster file didn't contain a character directory in the last 517 words. Replace the font, or better, change to using the {\tt.PK} equivalent. \item[\tt starting page number could not be found] --- The starting page (specified with the \verb+/STARTING_PAGE+ qualifier) does not match any page in the \DVI{} file. {\sloppy\item[\tt (VF file) Character \meta{char\_num} does not exist] \hfil --- The specified character has been used in the document, but that character does not exist within the virtual font. Use {\sf VFtoVP} to analyze the file.} {\sloppy\item[\tt (VF file) contains illegal command in character packet] \hfil --- The \linebreak[4] virtual font file contains an illegal command within a character packet. Use {\sf VFtoVP} to analyze the font file.} \item[\tt (VF file) First byte isn't `pre'] --- Virtual font files are expected to commence with a |pre| command; this file doesn't. Use {\sf VFtoVP} to analyze the file. {\sloppy\item[\tt (VF file) Illegal byte $x$ at start of character packet] \hfil --- The \linebreak[4] virtual font file contains an illegal command or font mapping command within or after one or more character packets. Use {\sf VFtoVP} to analyze the font file.} \item[\tt (VF file) invokes unmapped font $f$] --- The virtual font file references a font which it hasn't mapped; use {\sf VFtoVP}. \item[\tt (VF file) References too many fonts] --- The virtual font file at\-tempt\-ed to map more actual fonts than \DVItoLN{} was capable of handling; the font is probably infinitely recursive. Use {\sf VFtoVP} to analyze the file. \item[\tt (VF file) Mapped font size is too big] --- The virtual font references an actual font and the size of the latter, and the scale at which it is invoked, exceeds the legal limits for a virtual font. Use {\sf VFtoVP} to analyze the file. \item[\tt (VF file) Negative packet length] --- The virtual font file is malformed. Use {\sf VFtoVP} to analyze the file. {\sloppy\item[\tt (VF file) Wrong version number in second byte] --- The virtual font file is of a version not supported by \DVItoLN. Use {\sf VFtoVP} to analyze the file.} \item[\tt {VF packet failed [\meta{font\_number},\meta{char\_num}]}] --- Whilst processing \linebreak[4] stored glyphs for a complex character taken from a virtual font, \DVItoLN{} failed to position the elements of the glyph; this might require to be reported as for an internal error, but firstly use {\sf VFtoVP} to analyze the file. \item[\tt Where are the font directories? (/PK\_FONT\_DIRECTORY, etc)] \hfil ---\linebreak[4] The command line specified neither the \verb+/PK_FONT_DIRECTORY+ qualifier, nor \verb+/PXL_FONT_DIRECTORY+. At least one of these qualifiers ought to be supplied with a default value, through the command definition ({\tt DVITOLN03.CLD}) file. Speak to your local \TeX nician. \end{description} \subsection{Non-fatal Error Messages} Should one of the following errors be detected, \DVItoLN{} will attempt to continue with processing your \DVI{} file; however, the resultant output file will probably not produce the expected results. When the program finishes, the DCL symbol \verb+$SEVERITY+ will have the value $2$, thus permitting a command procedure to detect that an error occurred. Suggested error recovery techniques are given, when appropriate. Once again, the program {\sf DVItype} can provide a more detailed analysis of the errors. \begin{description} {\sloppy\item[\tt arithmetic overflow! parameter changed from $x$ to $y$] \hfil--- When \linebreak[4] processing \meta{dvi byte}s, a command was encountered that attempted to move the horizontal or vertical position to somewhere with a co\"ordinate exceeding $\pm(2^{31}-1)${\tt sp}. Since this would imply being about 38ft from the origin, perhaps you'd be better off using {\sf DVItoAd\-vert\-ising\-Hoard\-ing}!} \item[\tt backpointer in byte $m$ should be $p$] --- The program has detected an inconsistency between the start of the current page and the previous one. \item[\tt bad postamble pointer in byte $m$] --- the word following the |post_post| command is supposed to point back to the start of the postamble: this one didn't! \item[\tt bop occurred before eop] --- Whilst processing a page, a |bop| command was detected before finding the |eop| that should have terminated the current page. \item[\tt byte $m$ is not postpost] --- The byte following the end of the postamble is not the anticipated |post_post| command. {\sloppy\item[\tt character $c$ invalid in font \meta{name}] --- The \DVI{} file has requested that character $c$ be imaged from the currently selected font, and yet the font doesn't contain any such character; something might be printed, but it's anybody's guess as to what!} {\sloppy\item[\tt Couldn't open \bs special inclusion: \meta{file}] --- The \DVI{} file contained a \verb+\special{ln03:sixel +% \meta{file}\verb+}+ command, but the program was unable to open the specified file. The VMS-style error report associated with this message might indicate why the file couldn't be opened.} \item[\tt Diagonal rule in \bs special \meta{special\_pars}] --- A \verb+\special+ command requested the \verb+connect+ operation, but the points specified were not in the same vertical or horizontal line: this \verb+\special+ should only be issued by the macros of the {\tt changebar} style option, and not by the user. \item[\tt identification in byte $m$ should be $i$] --- The \DVI{} file is supposed to contain the version number (currently $2$) at the beginning and the end of the file; the byte-address $m$ indicates which one failed. {\sloppy\item[\tt Invalid point number in \bs special \meta{special\_pars}] --- A \verb+\special+ command, using the {\tt defpoint} or {\tt resetpoints} operations, specified an invalid point number ($>|max_points|$, which is a compile-time constant in the \Web), or the {\tt connect} operation specified a point that hadn't previously been defined.} \item[\tt non-ASCII character in \bs special command] --- The character string parameter of a \verb+\special+ command includes a character not in the {\sc Ascii} character set. \item[\tt ---not loaded, TFM file is bad] --- When reading a \TFM{} file, the program detected some discrepancy, which has probably already been reported. Use {\sf TFtoPL} to analyze the file. \item[\tt Null \bs special argument] --- A \verb+\special+ command has an empty argument. {\sloppy\item[\tt Point number missing] {\tt in \bs special} \meta{special\_pars} --- A point number was expected in a \verb+\special{ln03:defpoint}+ command.} \item[\tt pop illegal at level zero] --- Something's wrong with the \DVI{} file; it attempted to |pop| an environment when none had been stacked. {\sloppy\item[\tt postamble command within a page] --- Whilst processing a page, \DVItoLN{} discovered a |post| command, without any prior |eop|.} \item[\tt preamble command within a page] --- This \DVI{} file is {\em really\/} twisted: a |pre| command was found during a page. \item[\tt push deeper than claimed in postamble] --- The current environment \linebreak[4] was |push|ed more often than \TeX{} had claimed. \item[\tt reference to an unloaded font] --- An attempt has been made to set a character from a font which hadn't been defined within the \DVI{} file. \item[\tt \bs special string of negative length] --- The |xxx| command which \TeX{} uses to pass a \verb+\special+ command in the \DVI{} file invalidly indicated that the string was of negative length! \item[\tt \bs special string too long] --- Just as the previous error, but it was too large positively in this instance. \item[\tt stack not empty at end of page (level $s$)] --- When \TeX{} gets to the end of a page, it's supposed to ensure that all environments that it's instructed to have been saved shall be restored; this \DVI{} file contravenes that requirement. \item[\tt undefined command \meta{dvi\_byte}] --- The \DVI{} file contains a command that is undefined; are you sure it was produced by TeX? {\sloppy\item[\tt Unsupported or malformed \bs special \meta{special\_pars}] --- Couldn't find a \linebreak[4] properly formed operation code string in a \verb+\special+ command.} \item[\tt Unsupported \bs special \meta{special\_pars}] --- A \verb+\special+ command included an operation code, which whilst recognized, was inappropriate in the current context. \item[\tt VF checksum disagreed! TFM: $C_1$ VF: $C_2$] --- The sum check found in a {\tt.VF} file when reading a virtual font disagreed with that previously recorded in the font's \TFM{} file. \item[\tt VF design size disagreed! TFM: $S_1$ VF: $S_2$] --- The design size found in a {\tt.VF} file when reading a virtual font disagreed with that previously recorded in the font's \TFM{} file. \end{description} \subsection{Warning Messages} These messages generally indicate some problem that didn't prevent \DVItoLN{} from generating a valid output file; however, it might not print out as you had anticipated! Provided no errors occur, the exit status of the program will have a \verb+$SEVERITY+ of $0$, thus permitting a command procedure to detect that warning messages were issued. \begin{description} \item[\tt cannot find file \meta{file\_spec}] --- \DVItoLN{} failed to locate the file containing the (packed or unpacked) pixel rasters; it will proceed by substituting solid rules for each glyph. Remedy: Install the requisite font file on your system. {\sloppy\item[\tt Characters `\meta{text}' set off paper ( x = $x_s$..$x_e$, y = $y$ )] \hfil --- Some \linebreak[4] portion of the text is imaged outside that area of the paper which can be written by the printer. The $x$ values indicate the left- and right-hand limits of the text, whilst the $y$ value gives the vertical co\"ordinate of the baseline; all such dimensions are given in absolute pixel positions on the physical page. Perhaps you're printing something in landscape mode that was formatted to be printed in portrait, or vice versa?} \item[\tt checksum doesn't match; DVI=$C_1$ vs. TFM=$C_2$] --- When the font definition command was found in the \DVI{} file, its sum check was recorded; this should agree with that of the \TFM{} file itself, because it was written using the latter value when \TeX{} processed the source. Therefore this error indicates that you're trying to use different fonts from those read by \TeX\@. Remedy: Replace the font, or reprocess the source with \TeX. \item[\tt checksum doesn't match in PK file] --- The font's sum check as recorded in the packed pixel file disagrees with that in the \TFM{}\@. This would suggest that the font should be rebuilt, using \MF{} and {\sf GFtoPK}. \item[\tt checksum doesn't match in PXL file] --- The font's sum check as recorded in the unpacked pixel file disagrees with that in the \TFM{}\@. This would suggest that the font should be rebuilt, using \MF{} and {\sf GFtoPX}. \item[\tt ---checksum doesn't match previous definition] --- Each font definition appears twice in the \DVI{} file; the sum check recorded in the second definition disagrees with the first --- use {\sf DVItype}. \item[\tt denominator doesn't match the preamble] --- The denominator of the rational number which gives the size of each DVI unit (in decimicrons) which has been read from the postamble disagrees with that in the preamble --- use {\sf DVItype}. \item[\tt ---design size doesn't match previous definition] --- The font's design size in the second definition of the font disagrees with the first --- use {\sf DVItype}. {\sloppy\item[\tt Discarding earlier packet for character $c$] --- Whilst processing a \linebreak[4] virtual font file, a second definition for a character's glyph was encountered: the first definition will be discarded, and replaced by the last one --- use {\sf VFtoVP}.} \item[\tt extra junk at end of the VF file] --- Some unexpected bytes were discovered after the end of a virtual font ({\tt.VF}) file; to prevent this error recurring, use {\sf VFtoVP} to correct the error and rewrite the virtual font with {\sf VPtoVF}. {\sloppy\item[\tt Font \meta{name} doesn't contain character $c$] \hfil --- No definition was encountered for the glyph of character $c$ when the font file's rasters were read: the character will be imaged by the appropriate amount of whitespace.} \item[\tt ---font name doesn't match previous definition] --- The name of the font given in the second definition within the \DVI{} file disagrees with the original defining occurrence --- use {\sf DVItype}. \item[\tt magnification doesn't match the preamble] --- The magnification reported in the postamble disagreed with that in the preamble --- use {\sf DVItype}. {\sloppy\item[\tt Missing or unknown unit of measure: \meta{text}] --- A unit of measure \linebreak[4] was expected, either within a \verb+\special+ command, or associated with one of the qualifiers \verb+/TOP_MARGIN+, \verb+/LEFT_MARGIN+, \verb+/HFUZZ+ or \verb+/VFUZZ+. A supplementary message will indicate what \meta{physical unit} was assumed ({\tt pt} or {\tt sp}).} \item[\tt more than $m$ rules on page; excess ignored] --- A page contained too many separate rules; the program is restricted to $16384$ by the compile-time constant |max_rules|. Perhaps something's run amok in a \LaTeX{} {\tt picture} environment? {\sloppy\item[\tt not enough signature bytes at end of file ($m$)] \hfil--- \DVI{} files are \linebreak[4] supposed to end with at least four signature ($223$) bytes --- use {\sf DVItype}.} \item[\tt numerator doesn't match the preamble] --- The numerator of the rational fraction given in the postamble disagrees with that previously read from the preamble --- use {\sf DVItype}. \item[\tt /ORIENTATION must be PORTRAIT or LANDSCAPE;] {\tt assuming PORTRAIT} \hfil-- \linebreak[4] The \verb+/ORIENTATION+ qualifier was given an illegal value; this should never happen, unless the command definition file has been corrupted. \item[\tt Page deeper than TeX reported by $y$pt] --- Characters were positioned further down the page lower than \TeX{} had recorded in the \DVI{} file. This isn't an error, unless accompanied by an indication that characters were set off the paper. See description of the \verb+/VFUZZ+ qualifier. \item[\tt Page wider than TeX reported by $x$pt] --- Characters were imaged beyond the right-hand margin that \TeX{} had recorded in the \DVI{}. \cbstart This isn't an error, unless accompanied by an indication that characters were set off the paper\cbend. See description of the \verb+/HFUZZ+ qualifier. {\sloppy\item[\tt Pixel width discrepancy; font ]\meta{name} {\tt char} $c$ {\tt ---computed width: $W_c$; actual width: $W_a$} --- The width of the indicated character, in pixels, differed from that computed from the \TeX{} font metrics (by at least two pixels). The actual width is always used when imaging glyphs.} \item[\tt PK font pixels non-square] --- The {\sl aspect ratio\/} of the characters in the packed pixel file was not 1:1 --- will probably produce distorted glyphs, since the LN03 printer does print with square pixels. {\sloppy\item[\tt ---scaled size doesn't match previous definition] --- The second \linebreak[4] definition of the font provided a different scaled size from that in the first definition --- use {\sf DVItype}.} \item[\tt there are really $m$ pages, not $n$] --- Although the postamble claimed that there were $n$ pages in the document, there were really $m$ --- use {\sf DVItype}. \item[\tt ---this font was already defined] --- A spurious additional font definition was encountered in the \DVI{} file --- use {\sf DVItype}. \item[\tt ---this font wasn't loaded before] --- When reading the postamble, a definition was encountered for a font that wasn't previously defined in the body of the \DVI{} file --- use {\sf DVItype}. \item[\tt VF data not a multiple of 4 bytes] --- Virtual font files ({\tt.VF}) are supposed to be some multiple of 4 bytes long --- use {\sf VFtoVP}. \item[\tt VF file ended without postamble] --- Whilst reading glyph definitions from a virtual font file, the |post| command was met unexpectedly --- use {\sf VFtoVP}. \end{description} \subsection{Informational Messages} These are output to provide the user with an indication of the progress of the process of translating the \DVI{} file into an {\tt.LN3} file. If no other messages are output, you can be assured that the printed version will accord with what \TeX{} intended to put on the paper (although this might not be what {\em you\/} intended!) Provided that no warning or error messages were issued, the program's exit status will have a \verb+$SEVERITY+ of \verb+SS$_SUCCESS+ ($1$), thus permitting a command procedure to be confident that no warning or errors occurred. \begin{description} \item[\tt (\meta{file\_spec}\dots)] --- Whenever the \DVI{} file, or a file specified as a graphics inclusion, is opened, a left parenthesis and the full VAX/RMS file specification is reported on the terminal; when the file is closed, a matching right parenthesis is displayed. In the log (\TYP) file, the file specifications are accompanied by self-explanatory text. \item[{\tt [\meta{page\_no}]}] --- As \DVItoLN{} starts to process a page, a left bracket and the page number (which may consist of a series of integers, separated by periods) is displayed; when the end of the page is encountered, the matching right bracket is displayed. \item[\tt Finding starting page...found]\cbstart\footnotemark\cbend{} --- After the title has been displayed, \DVItoLN{} starts locating the first page to be printed; at the same time, it works out if any blank pages will need to be interspersed during printing. Since this operation can take a significant amount of time on a large document, the first part of this message is displayed so that the user won't think that the program has died; the `{\tt found}' is displayed when this processing is completed. \item[\tt Font \meta{name}] [{\tt (at $m$\%)}] {\tt loaded with} $n$ {\tt bytes of rasters (}$m$ {\tt\hyphenchar\the\font=`\- char\-act\-ers)}\cbstart\footnotemark\cbend{} --- The specified font (at the magnification shown, if not 100\%) has been included in the downloaded fonts; if $n$ seems very small, it may be because the glyphs of the font were too large to be downloaded and hence will be imaged individually wherever they appear. {\sloppy\item[\tt Font \meta{name}] [{\tt (at $m$\%)}] {\tt unavailable; printing rules for glyphs}\cbstart\footnotemark\cbend{} --- The specified font wasn't available at the requested magnification; characters from this font will be imaged by printing solid rules of size determined from the \TeX{} font metrics. Previously, a `{\tt cannot find file}' warning will have been issued for this font.} \item[\tt Font \meta{name}] [{\tt (at $m$\%)}] {\tt is virtual}\cbstart\footnotemark\cbend{} --- The specified font was a virtual one; this may result in the loading of real fonts other than those specified by \TeX{} when the \DVI{} file was generated. {\sloppy\item[\tt Gathering font usage statistics...done]\cbstart\footnote{All these messages are suppressed if the {\tt/NOVERBOSE} qualifier is used.}\cbend{} \hfil--- Once the starting page \linebreak[4] has been found, \DVItoLN{} makes one rapid pass through the \DVI{} file, noting which glyphs are used from each font. Doing this allows us to save time and space that would otherwise be wasted by downloading the whole of a font. It can take a significant amount of time, so the first part of this message is written to the display, and then an additional period will be displayed after processing every ten pages, thus giving the user an assurance that the program hasn't collapsed.} \item[\tt Reading from file \meta{file\_spec}] --- This message is written to the log (\TYP) file only, and records the full file specification of the \DVI{} file being processed. \item[\tt Sixel graphics included from: \meta{file\_spec}] --- This is recorded in the log (\TYP) file whenever a file is read by a \verb+\special{ln03:sixel}+ command. \item[\tt This is DVItoLN03, Vax/VMS Version $V$] --- This banner announcement identifies the version of the program, both on the screen and in the log (\TYP) file. \item[\tt Total of $n$ bytes of rasters downloaded] --- After all fonts have been downloaded, this message gives an indication of the total number of bytes that will be occupied by the downloaded fonts in the printer's memory. It can therefore be compared with the available memory, as reported on a printer test sheet (see~\cite{DEC:LN03}) to determine whether the resultant file can be printed correctly --- if there is insufficient memory, then process your document in smaller sections. {\bf N.B.} If a document contains any pages that are printed in landscape mode, all downloaded fonts will be reoriented to that mode automatically by the printer: this can result in overflowing the available memory. \end{description} \endgroup \chapend \bibliographystyle{unsrt} \addcontentsline{toc}{section}{References} \bibliography{local_guides} \end{document}